@gloom-sh/terminal 0.18.5 → 0.19.1

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

@@ -3,7 +3,7 @@ import { extname, isAbsolute, relative, resolve } from "path";
 import type { CliCommandContext, HeadlessArgumentExpansion } from "../../types/plugin";
 import type { MarketContext } from "../types";
 import { withMarketData } from "../context";
-import { cliStyles, renderStats, type CliStatEntry } from "../../utils/cli-output";
+import { buildForFile, cliStyles, renderForFile, renderStats, type CliStatEntry } from "../../utils/cli-output";
 import {
   filterPaneCatalogEntries,
   findFunctionCode,
@@ -35,13 +35,14 @@ import { withPersistedCloudSession } from "./cloud-session";
 import {
   ListingArgError, listingFateLoader, listingReadNotes, loadForListing, loadListingQuoteAnswer, quotedListingChoiceNotes, refuseMovedListing,
 } from "../listing-arg";
-import { isNotATickerMessage } from "../not-a-ticker";
-import { isCliFailure, SERVICE_UNREACHABLE_CODE } from "../errors";
-import { DATA_SERVICE_UNREACHABLE_MESSAGE } from "../../utils/network-failure";
+import { notATickerStop } from "../company-name-hint";
+import { CLI_ERROR_CODE, failUnreachable, failWithError, isCliFailure, unreachableError } from "../errors";
+import { DATA_SERVICE_UNREACHABLE_MESSAGE, isNetworkFailure } from "../../utils/network-failure";
 import { isTickerLinkPeer } from "../../layout/ticker-navigation";
 import { knownGapMessage, commandPointer, commandPointerLeads, topicPointer } from "../known-gaps";
 import { selectReportTables, type CliReportTables } from "../report-tables";
-import { cliOutputWritten, type CliErrorObject } from "../result";
+import { cliOutputWritten, printCliResult, serializeCliResult, type CliErrorObject } from "../result";
+import { checkOutputPath, resolveOutputPath, writeOutputFile } from "../output-file";
 import type { CatalogCommandHit } from "../unknown-command";
 import { CLI_EXIT_CODES } from "../exit-codes";
 import { shotOptionRefusal } from "./shot-options";
@@ -263,7 +264,7 @@ export function reportFailure(
   const reasons = [...data.errors ?? [], ...typeof data.reason === "string" ? [data.reason] : []];
   const unreached = reasons.filter((reason) => reason.includes(DATA_SERVICE_UNREACHABLE_MESSAGE));
   if (unreached.length > 0 && (data.empty || data.unavailableSymbols.length > 0)) {
-    return { code: SERVICE_UNREACHABLE_CODE, message: `${asked}: ${unreached.join("; ")}.`.replace(/\.\.$/, "."), retryable: true };
+    return unreachableError(`${asked}: ${unreached.join("; ")}.`.replace(/\.\.$/, "."));
   }
   if (!data.empty && !(noListing && noValues) && !(failsWithoutData && foundNothing(data))) return null;
   const unavailable = data.unavailableSymbols.length > 0 ? `no data for ${data.unavailableSymbols.join(", ")}` : "no data";
@@ -276,6 +277,16 @@ export async function runPaneFunction(args: string[], ctx: CliCommandContext) {
       if (parsed.strict) {
         throw new Error("--strict is an option of shot. fn takes --require-bot-safe to fail on a report that is not complete.");
       }
+      // What only a capture draws is refused, never ignored: the report would print as if it had not been given.
+      if (parsed.shotOnly?.length) {
+        const one = parsed.shotOnly.length === 1;
+        const shot = ["gloom shot", resolved.token, parsed.arg.trim() && commandWord(parsed.arg.trim())].filter(Boolean).join(" ");
+        throw new Error(`${parsed.shotOnly.join(" and ")} ${one ? "is an option" : "are options"} of shot, which saves the pane as a PNG; fn prints the report. `
+          + `Drop ${one ? "it" : "them"} from fn, or capture the pane with ${shot}.`);
+      }
+      // The file --output names, checked before the report loads so a path that cannot be written fails at once.
+      const outputPath = parsed.outputPath === null ? null : resolveOutputPath(parsed.outputPath);
+      if (outputPath) await checkOutputPath(outputPath);
       if (parsed.requireBotSafe && (
         !resolved.capability.botSafe || resolved.capability.reportReadiness !== "ready"
       )) {
@@ -305,22 +316,25 @@ export async function runPaneFunction(args: string[], ctx: CliCommandContext) {
         : null;
       const moved = { command: "fn", retry: (key: string) => `gloom fn ${resolved.token} ${key}` };
       // A report that fails or comes back empty for an exchange the symbol is not listed on says so.
+      // A report written to a file is drawn for it as it is built: no colour and no terminal width, as a redirect gets it.
+      const buildReport = () => buildFunctionReport(resolved, context, parsed.arg);
       const report = await refuseMovedListing(fate, moved, () => withPersistedCloudSession(
         context,
         () => loadForListing(
           parsed.listing ?? [],
           context,
           ctx,
-          () => buildFunctionReport(resolved, context, parsed.arg),
+          outputPath ? () => buildForFile(buildReport) : buildReport,
           (built) => built.data.empty || !built.data.complete,
         ),
       ));
       // A company's name typed where its ticker goes (`fn RDCF Palantir`) found nothing: the answer is `quote`'s,
-      // "Not a ticker: PALANTIR. Try `gloom search Palantir`.", not an empty report.
-      if (quoteAnswer && (report.data.empty || report.data.unavailableSymbols.length > 0)) {
+      // "Not a ticker: PALANTIR. Did you mean PLTR (Palantir Technologies Inc.)?", not an empty report. A source that
+      // could not answer for the word (a timeout) says nothing of it, but when search finds the company it is that.
+      if (quoteAnswer && listing && (report.data.empty || report.data.unavailableSymbols.length > 0)) {
         const { quote, error } = await quoteAnswer();
-        const message = error instanceof Error ? error.message : null;
-        if (!quote && isNotATickerMessage(message)) ctx.fail(message!);
+        const stop = quote ? null : await notATickerStop(error, listing, context);
+        if (stop) ctx.fail(stop);
       }
       if (parsed.requireBotSafe && (report.data.empty || !report.data.complete)) {
         const unavailable = report.data.unavailableSymbols.length > 0
@@ -347,10 +361,24 @@ export async function runPaneFunction(args: string[], ctx: CliCommandContext) {
       const failure = reportFailure(report.data, ["fn", resolved.token, parsed.arg.trim()].filter(Boolean).join(" "), {
         failsWithoutData: resolved.headless?.failsWithoutData, tables: report.tables });
       // The report states its own freshness in its data and text; JSON cites it as `source` too.
-      ctx.printResult({ data, exportFreshness: report.data.freshness, ...(warnings.length > 0 ? { warnings } : {}), ...(failure ? { failure } : {}) }, {
+      const result = { data, exportFreshness: report.data.freshness, ...(warnings.length > 0 ? { warnings } : {}), ...(failure ? { failure } : {}) };
+      const render = {
         text: () => glossary ? `${report.text}\n\n${renderReportGlossary(resolved.token, glossary)}` : report.text,
         ...(tabular ? { tables: selectReportTables(report.tables, resolved.tableSection) } : {}),
-      });
+      };
+      if (outputPath) {
+        // A report with no data writes no file: a header alone would read as a screen that matched nothing. It fails
+        // as plain --json fails, with its code and whether to retry.
+        if (failure) failWithError({ ...failure, details: `Nothing was written to ${outputPath}.` });
+        await writeOutputFile(outputPath, `${renderForFile(() => serializeCliResult(result, ctx.cliOptions, render))}\n`);
+        // What was written and where; warnings go to stderr as they would beside printed rows, and JSON keeps its envelope.
+        const saved = { output: outputPath, format: ctx.cliOptions.format, rows: report.data.rowCount };
+        printCliResult({ data: saved, ...(warnings.length > 0 ? { warnings } : {}) },
+          { ...ctx.cliOptions, format: ctx.cliOptions.format === "json" ? "json" : "text" },
+          { text: () => `Saved ${outputPath}` });
+        return;
+      }
+      ctx.printResult(result, render);
       if (failure) process.exitCode = CLI_EXIT_CODES.error;
     }, { strictHeadlessOptions: true, tableSection: true });
   });
@@ -437,6 +465,11 @@ async function capturePaneScreenshot(args: string[], ctx: CliCommandContext, onS
         fitRows: parsed.heightGiven !== true,
         options: parsed.options,
         onStalledReport,
+      }).catch(async (error: unknown) => {
+        // A company's name typed where its ticker goes fails as `fn` words it, with the company search finds.
+        const { quote, error: quoteError } = parsed.listing ? await loadListingQuoteAnswer(context.dataProvider, parsed.listing) : { quote: null, error: undefined };
+        const stop = parsed.listing && !quote ? await notATickerStop(quoteError, parsed.listing, context) : null;
+        throw stop ? new Error(stop) : error;
       });
       if (parsed.requireBotSafe && !result.usable) {
         throw new Error(
@@ -508,7 +541,8 @@ export async function runPaneFunctionHelp(command: string, args: string[], ctx:
         const found = findPaneFunction(registry, target);
         if (!found?.pane) return undefined;
         const { template, pane } = found;
-        const entries = await buildPaneCatalogEntries(registry, context);
+        // A function typed by its code is helped even while it is unlisted.
+        const entries = await buildPaneCatalogEntries(registry, context, { unlisted: true });
         // A pane named directly, where functions open it, is helped by the first of them.
         return (template ? entries.find((candidate) => candidate.templateId === template.id) : undefined)
           ?? entries.find((candidate) => candidate.paneId === pane.id);
@@ -578,11 +612,15 @@ async function runPaneCliCommand(ctx: CliCommandContext, run: () => Promise<void
   try {
     await run();
   } catch (error) {
-    // A failure with fields for --json (`ticker_moved`, its change and retry) keeps its code and them.
-    if (isCliFailure(error) && error.fields) throw error;
+    // A failure with fields for --json (`ticker_moved`, its change and retry), or a code of its own (`no_data`,
+    // `service_unreachable` and whether to retry), keeps them.
+    if (isCliFailure(error) && (error.fields || error.code !== CLI_ERROR_CODE)) throw error;
     // A listing it cannot use says what to type instead; a name that opens nothing, what is close to it.
     if (error instanceof ListingArgError || error instanceof UnknownPaneFunctionError) ctx.fail(error.message, error.details || undefined);
     const message = error instanceof Error ? error.message : String(error);
+    // Nothing answered: said as every command says it, with what to check.
+    if (message.includes(DATA_SERVICE_UNREACHABLE_MESSAGE)) failUnreachable(message);
+    if (isNetworkFailure(error)) failUnreachable();
     // A failure the command already worded keeps its advice line.
     const stated = error instanceof Error ? (error as Error & { details?: unknown }).details : undefined;
     const details = typeof stated === "string" ? stated : undefined;

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

@@ -8,7 +8,7 @@ import {
   nextRegularSessionOpen,
 } from "../../market-data/market/freshness";
 import { futuresWeekendClosure } from "../../market-data/market/futures-week";
-import { currentFxClosureStart } from "../../utils/fx-market-hours";
+import { currentFxClosureStart, isFxMarketOpen } from "../../utils/fx-market-hours";
 import { zonedDateKey } from "../../utils/zoned-date-time";
 import type { ReportTime } from "../../utils/utc-time";
 import type { QuoteIndexSession } from "../../types/financials";
@@ -60,6 +60,10 @@ const US_EXCHANGE_TIME_ZONE = "America/New_York";
  */
 function venueSession(exchange: string, marketState: string | undefined, now: number, calendar?: QuoteIndexSession): VenueSession | null {
   if (isAlwaysOpenExchange(exchange)) return { state: "always" };
+  // Spot FX trades its week, Sunday 17:00 to Friday 17:00 New York, by the clock as an exchange rate's line has it.
+  // A source's own state is not its week: Yahoo stamps a pair CLOSED from that open to London's midnight, which read
+  // `markets closed` beside `fx`'s `markets open` for the same pair.
+  if (exchange === FX_VENUE) return { state: isFxMarketOpen(now) ? "open" : "closed" };
   const next = nextRegularSessionOpen(exchange, now);
   if (next) {
     const { timeZone } = next;
@@ -125,10 +129,13 @@ function closeDateOf(observation: SessionObservation, session: VenueSession, now
   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.
+  // at 17:00: a print from that last day, after Thursday's 17:00 close through
+  // Friday's, is that Friday's close. A tick after it, over the weekend, is no
+  // price of the week and keeps its own time.
   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 (weekClose != null) {
+    return time.time > weekClose - DAY_MS && time.time <= weekClose ? 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;
@@ -151,6 +158,22 @@ function closeMarketOf(exchange: string, session: VenueSession): string | null {
   return isUsListingExchange(exchange) ? "US" : exchange;
 }
 
+/**
+ * The market a venue's sessions belong to, as a report that mixes markets
+ * names it: `US` for the US listing venues, which share one calendar (and an
+ * index publisher's sessions dated in New York), `FX` for currency pairs, the
+ * venue's code for any other the app has a calendar of (`LSE`). Null for one
+ * known only by the state its source stamps (an index publisher dated
+ * elsewhere, a futures venue), whose open a report cannot name: its sessions
+ * are still dated by venue (`reportVenueSessionDates`), as they always were.
+ */
+function sessionMarketOf(exchange: string, session: VenueSession): string | null {
+  if (exchange === FX_VENUE) return "FX";
+  if (session.quoted) return session.timeZone === US_EXCHANGE_TIME_ZONE ? "US" : null;
+  if (!session.timeZone) return null;
+  return isUsListingExchange(exchange) ? "US" : exchange;
+}
+
 /** One market's session behind a report that mixes markets: its local date, and whether that session has closed. */
 export interface VenueSessionDate {
   /** `US` for the US listing venues, which share one calendar, the venue's code elsewhere (`XETRA`, `EPA`). */
@@ -192,6 +215,45 @@ export function reportVenueSessionDates(observations: readonly SessionObservatio
   });
 }
 
+/** One market behind a report that mixes markets, and where it stands now (`reportVenueMarkets`). */
+export interface VenueMarket extends ReportMarket {
+  /** The market as `sessionMarketOf` names it: `US`, `FX`, or the venue's code (`LSE`). */
+  market: string;
+}
+
+/** The fewest and most markets a report names one by one; past that a line of them would not be read. */
+const MIN_NAMED_MARKETS = 2;
+const MAX_NAMED_MARKETS = 3;
+
+/**
+ * Where each market behind a report that mixes two or three stands now, each
+ * with its own next open (`LSE` opens 08:00 UTC, `US` 13:30 UTC), in the
+ * order the markets first appear. Empty for one market, more than three, or
+ * any that cannot be placed or named (one trading around the clock among them,
+ * an index publisher with no calendar).
+ */
+export function reportVenueMarkets(observations: readonly SessionObservation[], now: number): VenueMarket[] {
+  const markets = new Map<string, VenueSession>();
+  for (const observation of observations) {
+    const exchange = canonicalExchange(observation.exchange);
+    if (!exchange) continue;
+    const session = venueSession(exchange, observation.marketState, now, observation.calendar);
+    const market = session && session.state !== "always" ? sessionMarketOf(exchange, session) : null;
+    if (!session || !market) return [];
+    if (!markets.has(market)) markets.set(market, session);
+  }
+  if (markets.size < MIN_NAMED_MARKETS || markets.size > MAX_NAMED_MARKETS) return [];
+  return [...markets].map(([market, session]) => ({
+    market,
+    state: session.state as ReportMarketState,
+    ...(session.next && session.state !== "open" && session.state !== "after-hours" ? {
+      reopensAt: new Date(session.next.open).toISOString(),
+      reopensOn: session.next.date,
+      ...(session.next.firstTrade ? { firstTrade: true as const } : {}),
+    } : {}),
+  }));
+}
+
 /**
  * Where the markets behind a quote report stand now, and whether the newest
  * observation is a close, and whose. Null market when the venues disagree

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

@@ -53,6 +53,8 @@ export interface ParsedPaneFunctionArgs {
   requireBotSafe: boolean;
   /** `shot --strict`: exit with the unusable-shot code when the capture shows no usable data. */
   strict?: boolean;
+  /** The options only `shot` reads (`--theme`, `--height`), as typed, which `fn` refuses rather than ignore. */
+  shotOnly?: string[];
   /** The listing a one-ticker function's argument named, once `applyListingArgument` has resolved it. */
   listing?: CliListing;
   /**
@@ -112,10 +114,18 @@ export type OptionValueWords = (key: string) => number;
 /** Words in the last value of a list (`TRY -20, EUR 5` ends with two); a decimal comma (`TRY -2,5`) separates nothing. */
 const lastValueWords = (value: string) => value.split(/(?<!\d),|,(?!\d)/).at(-1)!.trim().split(/\s+/).filter(Boolean).length;
 
+/**
+ * What only `shot` draws: the capture's height, theme, text scale, watermark
+ * and status line. `--width` is not one: on `fn` it is the CLI's table width.
+ */
+const SHOT_ONLY_KEYS = new Set(["height", "theme", "scale", "watermark"]);
+
 export function parsePaneFunctionArgs(
   args: string[],
   globalOptions: { limit?: number; tail?: number } = {},
   valueWords?: OptionValueWords,
+  /** Whether an option takes a list, so its flag typed again adds to it rather than replacing it. */
+  listOption?: (key: string) => boolean,
 ): ParsedPaneFunctionArgs {
   const positionals: string[] = [];
   const options: Record<string, string | true> = {};
@@ -131,6 +141,7 @@ export function parsePaneFunctionArgs(
   let strict = false;
   let requireBotSafe = false;
   const clamped: ShotSizeClamp[] = [];
+  const shotOnly: string[] = [];
 
   for (let index = 0; index < args.length; index += 1) {
     const token = args[index]!;
@@ -151,6 +162,7 @@ export function parsePaneFunctionArgs(
     // A switch: the token after it is the function's argument, never its value.
     if (normalizeOptionKey(key) === "noStatus" && inlineValue === undefined) {
       status = false;
+      shotOnly.push(`--${key}`);
       continue;
     }
     if (normalizeOptionKey(key) === "explain" && inlineValue === undefined) {
@@ -165,6 +177,7 @@ export function parsePaneFunctionArgs(
     const nextValue = inlineValue === undefined && next && !next.startsWith("--") ? args[++index] : true;
     let value: string | true = inlineValue ?? nextValue ?? true;
     const normalizedKey = normalizeOptionKey(key);
+    if (SHOT_ONLY_KEYS.has(normalizedKey)) shotOnly.push(`--${key}`);
     // A value that is a pair (`--fx-shift TRY -20`) takes the words after it, and a list of them the words after a comma.
     const words = value === true ? 1 : valueWords?.(normalizedKey) ?? 1;
     if (words > 1 && value !== true) {
@@ -172,13 +185,17 @@ export function parsePaneFunctionArgs(
         && (lastValueWords(value) < words || value.trimEnd().endsWith(","))) {
         value = `${value} ${args[++index]!}`;
       }
+    }
+    // A list's flag typed again adds to it: `--metric trailingPE --metric dividendYieldPercent`.
+    if ((words > 1 || listOption?.(normalizedKey)) && value !== true) {
       const earlier = options[normalizedKey];
       if (typeof earlier === "string") value = `${earlier}, ${value}`;
     }
     if (normalizedKey === "requireBotSafe" || normalizedKey === "botSafe") {
       requireBotSafe = value === true || String(value).toLowerCase() === "true";
     } else if (normalizedKey === "output" || normalizedKey === "out" || normalizedKey === "o") {
-      outputPath = value === true ? null : value;
+      // A flag with no path is kept as an empty one, which `fn` refuses rather than print as if it had not been given.
+      outputPath = value === true ? "" : value;
     } else if ((normalizedKey === "width" || normalizedKey === "height") && value !== true) {
       const size = parseShotSize(normalizedKey, value);
       if (size.used !== size.requested) clamped.push(size);
@@ -214,6 +231,7 @@ export function parsePaneFunctionArgs(
     ...(heightGiven ? { heightGiven: true as const } : {}),
     ...(explain ? { explain } : {}),
     ...(strict ? { strict } : {}),
+    ...(shotOnly.length > 0 ? { shotOnly } : {}),
   };
 }
 

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

@@ -19,12 +19,15 @@ import { splitSymbolArgs, stripStrayEdges } from "../symbol-args";
 import { readNameEntries } from "../name-entries";
 import { bankFigurePointer } from "../known-gaps";
 import { readTerminalCodeArg } from "../../tickers/company-name-listing";
+import { unknownBloombergMarket } from "../../tickers/terminal-codes";
+import { notATickerWords } from "../company-name-hint";
 import type { MarketContext } from "../types";
 import {
   buildPaneFunctionLookup,
   buildTemplateContext,
   findFunctionCode,
   nearFunctionCodes,
+  paneFunctionCode,
   suggestedFunctionCodes,
   suggestPaneFunctions,
   type NearFunctionCode,
@@ -142,8 +145,9 @@ export function parsePaneFunctionArgsFor(
   const found = parsed.target ? findPaneFunction(registry, parsed.target) : null;
   if (!found?.pane) return parsed;
   const capability = getPaneFunctionCapability(found.template, found.pane);
-  if (!capability.options.some((option) => (option.valueWords ?? 1) > 1)) return parsed;
-  return parsePaneFunctionArgs(args, globalOptions, (key) => findCapabilityOption(capability, key)?.valueWords ?? 1);
+  if (!capability.options.some((option) => (option.valueWords ?? 1) > 1 || option.list)) return parsed;
+  return parsePaneFunctionArgs(args, globalOptions, (key) => findCapabilityOption(capability, key)?.valueWords ?? 1,
+    (key) => findCapabilityOption(capability, key)?.list === true);
 }
 
 /**
@@ -168,11 +172,17 @@ export async function applyListingArgument(
   const takesOneTicker = kind === "ticker";
   const takesList = kind === "tickers" || kind === "symbol-list" || (!headless && kind === "ticker-list");
   // A function with an exchange option of its own (DIST) keeps it.
-  // A ticker with spaces is no listing, unless it is a terminal's code for one ("JPM US Equity").
-  if (!(takesOneTicker || takesList) || (takesOneTicker && /\s/.test(args.arg) && !await readTerminalCodeArg(context.dataProvider, args.arg))
-    || getPaneFunctionCapability(found.template, found.pane).options.some((option) => option.key === "exchange")) {
+  if (!(takesOneTicker || takesList) || getPaneFunctionCapability(found.template, found.pane).options.some((option) => option.key === "exchange")) {
     return args;
   }
+  // A ticker with spaces is no listing, unless it is a terminal's code for one ("JPM US Equity"). A company's name
+  // typed there (`fn RDCF "Palantir Technologies"`) stops before a report of dashes is drawn, as `quote` words a
+  // name that is no ticker, with the company search finds for it.
+  if (takesOneTicker && /\s/.test(args.arg) && !await readTerminalCodeArg(context.dataProvider, args.arg)) {
+    // A line written as a code with a market no venue answers to ("AAPL GP") is refused as the resolver words it.
+    if (unknownBloombergMarket(args.arg)) await resolveCliListing(args.arg, undefined, context);
+    throw new ListingArgError(await notATickerWords(args.arg, context));
+  }
   const exchange = typeof args.options.exchange === "string" ? args.options.exchange : undefined;
   const { exchange: _exchange, ...options } = args.options;
   // A list entry with spaces, or an argument of words, is a company's name search finds, or the symbols it holds.
@@ -225,9 +235,10 @@ export async function applyListingArgument(
   if (refusals.length > 0) {
     listings = listings.filter((listing) => !refusals.some((entry) => entry.listing === listing));
     if (listings.length === 0) {
-      throw new ListingArgError(refusals.map(({ refusal }) => refusal.message).join("\n"), refusals.map(({ refusal }) => refusal.details).join("\n"));
+      const details = refusals.flatMap(({ refusal }) => refusal.details ? [refusal.details] : []).join("\n");
+      throw new ListingArgError(refusals.map(({ refusal }) => refusal.message).join("\n"), details || undefined);
     }
-    notes.push(...refusals.map(({ refusal }) => `${refusal.message} ${refusal.details}`));
+    notes.push(...refusals.map(({ refusal }) => [refusal.message, refusal.details].filter(Boolean).join(" ")));
   }
   const usOnly = headless?.usListingsOnly;
   const abroad = usOnly ? listings.filter((listing) => listingAbroadVenue(listing.key) != null) : [];
@@ -348,7 +359,7 @@ export async function resolvePaneFunction(
     tableSection = taken.tableSection;
   }
   // What the user types for the function, which every error about it names.
-  const token = template?.shortcut?.prefix ?? template?.id ?? pane.id;
+  const token = paneFunctionCode(template, pane);
   // A word after a function that takes none is most often one of its option values (`fn JODI gas`).
   // Every function the catalog lists with no argument refuses one, a rendered view (HALT) as a report (CBR).
   // The catalog lists templates and the panes no template opens (HELP); a pane opened by its id stands for its templates.

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

@@ -4,6 +4,7 @@ import type { DesktopPaneShotPayload, DesktopPaneShotRenderResult } from "../des
 import type { ResolvedPaneFunction } from "./resolver";
 import type { RemoteUiNodeSnapshot } from "../../remote/types";
 import { accessGateSentence, accessGateStatus } from "./access-gate";
+import { isDataPaneForDomFallback } from "./capabilities";
 import { paneEvidenceMismatches, paneScreenshotEvidenceHook } from "./screenshot-evidence";
 import { collectShotSymbols } from "./data";
 import { renderedReportNotices } from "./report-notices";
@@ -21,10 +22,9 @@ import {
 import { shotExpectedChart, chartEvidenceMismatchesFor, intradayChartEvidenceMismatchesFor } from "./screenshot-chart-evidence";
 
 export function isPaneScreenshotUsable(signals: PaneScreenshotReadinessSignals): boolean {
-  return signals.rowCount > 0
+  return (signals.interactive || (signals.rowCount > 0 && !signals.emptyStateDetected))
     && !signals.loadingStateDetected
     && !signals.errorStateDetected
-    && !signals.emptyStateDetected
     && signals.complete
     && !signals.semanticMismatch
     && (!signals.requiresStructuredDataEvidence || signals.hasStructuredDataEvidence);
@@ -111,12 +111,14 @@ export function assessPaneScreenshot(
   const semanticMismatch = missingExpectedText.length > 0
     || missingExpectedSelections.length > 0
     || chartEvidenceMismatches.length > 0;
+  // Layouts and the other panes that are surfaces to operate have no rows to count: a capture of one is not empty for that.
+  const interactive = !isDataPaneForDomFallback(resolved.pane);
   const empty = render.loadingStateDetected
     || render.errorStateDetected
-    || render.emptyStateDetected
-    || rowCount === 0
+    || (!interactive && (render.emptyStateDetected || rowCount === 0))
     || semanticMismatch;
   const usable = isPaneScreenshotUsable({
+    interactive,
     rowCount,
     loadingStateDetected: render.loadingStateDetected,
     errorStateDetected: render.errorStateDetected,

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

@@ -108,6 +108,11 @@ export type PaneScreenshotDataEvidence =
   | PaneScreenshotEvidence;
 
 export interface PaneScreenshotReadinessSignals {
+  /**
+   * A surface to operate rather than data to read (Layouts, Brokers): its rows
+   * and an empty-state marker inside it say nothing of whether it rendered.
+   */
+  interactive?: boolean;
   rowCount: number;
   loadingStateDetected: boolean;
   errorStateDetected: boolean;

package/src/cli/quote-answer.ts

@@ -14,8 +14,8 @@ import { knownGapForTicker } from "./known-gaps";
 import {
   futuresTryLine,
   isNoProviderError,
+  isUnsettledNoProvider,
   listingChoiceNotes,
-  listingReadNotes,
   ListingArgError,
   loadBareVenues,
   notTradedMessage,
@@ -29,6 +29,7 @@ import {
   type ListingVenue,
 } from "./listing-arg";
 import { withListingSuggestion } from "./not-a-ticker";
+import { notATickerWords } from "./company-name-hint";
 import { isNetworkFailure } from "../utils/network-failure";
 import type { MarketContext } from "./types";
 
@@ -85,8 +86,8 @@ export async function answerQuote(
   const also = (quote: Quote) => root && quote.instrumentType?.trim().toUpperCase() !== "INDEX"
     ? [indexRootAlsoLine(root, request.command)] : [];
   if (result.quote) {
-    // "CAR = Avis Budget Group, NASDAQ (also XETRA, ASX)" names the venue too, so it replaces "SXR8 -> XETRA".
-    const choice = venues ? await listingChoiceNotes(listing, market, result.quote, venues) : listingReadNotes(listing);
+    // "CAR = Avis Budget Group, NASDAQ (different companies on XETRA, ASX)" names the venue too, so it replaces "SXR8 -> XETRA".
+    const choice = await listingChoiceNotes(listing, market, result.quote, venues);
     const venue = choice.length > 0 ? null : bareListingNote(listing, result.quote);
     // A row saved as 247540:KRX is quoted from KOSDAQ, the board it trades on.
     const board = tradingBoardNote(listing, result.quote);
@@ -132,8 +133,12 @@ export async function answerQuote(
  * A company's name typed as one word (`Apple`) that the source says is not a
  * ticker, answered as the listing search names for it with the line saying so
  * ("Read "Apple" as AAPL:NASDAQ (Apple Inc.)."), as a name of several words
- * is. Null when the word names no company, or that listing has no quote
- * either: the word keeps its own "Not a ticker".
+ * is. A source that could not answer for the word (a timeout, a rate limit)
+ * says nothing of it, but when search resolves it to a company, it is read the
+ * same way; when that listing has no quote either, the row says the word is not
+ * a ticker and names the company. Null when the word names no company, or that
+ * listing has no quote though the source did say "not a ticker": the word keeps
+ * its own answer.
  */
 async function answerCompanyName(
   result: QuoteBatchResult,
@@ -143,18 +148,24 @@ async function answerCompanyName(
   refresh: boolean,
   datesChangeBasis: boolean,
 ): Promise<QuoteAnswer | null> {
-  if (!listing.typed || listing.exchange || !notATickerSymbol(errorMessage(result.error) ?? "")) return null;
+  if (!listing.typed || listing.exchange) return null;
+  const notATicker = !!notATickerSymbol(errorMessage(result.error) ?? "");
+  const unsettled = !notATicker && isUnsettledNoProvider(result.error);
+  if (!notATicker && !unsettled) return null;
   const named = await oneWordCompanyName(listing.typed, market);
-  if (!named) return null;
+  // A real ticker a source failed to quote is not a company's name, even when the company carries the word.
+  if (!named || (unsettled && named.symbol.toUpperCase() === listing.symbol.toUpperCase())) return null;
   // A listing on a venue the app cannot read is no answer: the word keeps its own "Not a ticker".
   const resolved = await resolveCliListing(named.key, null, market).catch((error: unknown) => {
     if (error instanceof ListingArgError) return null;
     throw error;
   });
-  if (!resolved) return null;
-  const found = { ...resolved, readAs: named.readAs, ...named.meant ? { meant: named.meant } : {} };
-  const [quoted] = await market.dataProvider.getQuotesBatch([found.request], { forceRefresh: refresh, revalidate: true, datesChangeBasis });
-  return quoted?.quote ? answerQuote(quoted, found, market, request, refresh, null, { datesChangeBasis }) : null;
+  const found = resolved ? { ...resolved, readAs: named.readAs, ...named.meant ? { meant: named.meant } : {}, ...named.readFromName ? { readFromName: named.readFromName } : {} } : null;
+  const [quoted] = found ? await market.dataProvider.getQuotesBatch([found.request], { forceRefresh: refresh, revalidate: true, datesChangeBasis }) : [];
+  if (found && quoted?.quote) return answerQuote(quoted, found, market, request, refresh, null, { datesChangeBasis });
+  if (!unsettled) return null;
+  const sentence = await notATickerWords(listing.typed, market);
+  return { result: { ...result, error: new Error(sentence) }, listing, notes: [] };
 }
 
 /** A listing a command found a quote for, with what `quote` says beside it. */

package/src/cli/saved-copy-persistence.ts

@@ -0,0 +1,88 @@
+import type { AppResourceStorePort } from "../core/app-service-ports";
+import type { JsonValue } from "../data/sqlite/json";
+import type { PersistedResourceValue } from "../types/persistence";
+import type { PluginPersistence } from "../types/plugin";
+import { logFailure } from "../utils/log-failure";
+
+type SetResourceOptions = Parameters<PluginPersistence["setResource"]>[3];
+
+/**
+ * A plugin's persistence in a command: what the command fetches through a
+ * plugin's cache is saved in the profile, under the namespace the app keeps
+ * it in (`plugin:<state id>`), so a later run whose refresh fails answers
+ * from that saved copy as the app does. Only a read that may take an expired
+ * copy (`allowExpired`, what a cache falls back to when its refresh fails)
+ * reaches the saved copies; any other read sees only what this run fetched,
+ * so a command still asks for current data rather than answering from the
+ * app's cache. Plugin state is not read or kept. With no resource store,
+ * nothing outlives the run.
+ *
+ * The profile's store closes when the command ends, while a plugin may keep
+ * the persistence it was set up with: `release()` leaves the store alone from
+ * then on, and a store that fails (closed, full) costs the saved copy only,
+ * never the command.
+ */
+export function createCommandPluginPersistence(
+  resources: AppResourceStorePort | null | undefined,
+  namespace: string,
+): PluginPersistence & { release(): void } {
+  const fetched = new Map<string, PersistedResourceValue<unknown>>();
+  const keyOf = (kind: string, key: string) => `${kind}:${key}`;
+  let store = resources ?? null;
+  const saved = <T>(operation: string, run: (store: AppResourceStorePort) => T, fallback: T): T => {
+    if (!store) return fallback;
+    try {
+      return run(store);
+    } catch (error) {
+      return logFailure("cli.saved-copies", `${operation} a saved copy failed`, fallback)(error);
+    }
+  };
+  return {
+    release: () => { store = null; },
+    getState: () => null,
+    setState: () => {},
+    deleteState: () => {},
+    getResource: <T = unknown>(kind: string, key: string, options?: { sourceKey?: string; schemaVersion?: number; allowExpired?: boolean }) => {
+      const own = fetched.get(keyOf(kind, key)) as PersistedResourceValue<T> | undefined;
+      if (own || !options?.allowExpired) return own ?? null;
+      const record = saved("Reading", (resources) => resources.get<T>(
+        { namespace, kind, entityKey: key, sourceKey: options.sourceKey },
+        { schemaVersion: options.schemaVersion, allowExpired: true },
+      ), null);
+      return record && {
+        value: record.value,
+        fetchedAt: record.fetchedAt,
+        staleAt: record.staleAt,
+        expiresAt: record.expiresAt,
+        sourceKey: record.sourceKey,
+        schemaVersion: record.schemaVersion,
+        provenance: record.provenance,
+        stale: record.stale,
+        expired: record.expired,
+      };
+    },
+    setResource: <T = unknown>(kind: string, key: string, value: T, options: SetResourceOptions) => {
+      const fetchedAt = Date.now();
+      const entry: PersistedResourceValue<T> = {
+        value,
+        fetchedAt,
+        staleAt: fetchedAt + options.cachePolicy.staleMs,
+        expiresAt: fetchedAt + options.cachePolicy.expireMs,
+        sourceKey: options.sourceKey ?? "",
+        schemaVersion: options.schemaVersion ?? 1,
+        provenance: options.provenance ?? null,
+      };
+      fetched.set(keyOf(kind, key), entry);
+      saved("Writing", (resources) => resources.set<T>({ namespace, kind, entityKey: key, sourceKey: options.sourceKey }, value, {
+        cachePolicy: options.cachePolicy,
+        schemaVersion: options.schemaVersion,
+        provenance: options.provenance as JsonValue | null | undefined,
+      }), undefined);
+      return entry;
+    },
+    deleteResource: (kind: string, key: string, options?: { sourceKey?: string }) => {
+      fetched.delete(keyOf(kind, key));
+      saved("Deleting", (resources) => resources.delete({ namespace, kind, entityKey: key, sourceKey: options?.sourceKey }), undefined);
+    },
+  };
+}

package/src/cli/ticker-resolution.ts

@@ -85,7 +85,8 @@ export interface CliTicker {
   /**
    * A bare coin ticker (ETH) read as a listing that is not the coin, such as a
    * fund named for it: "ETH is Grayscale Ethereum Mini Trust ETF, not ethereum.
-   * For ethereum use ETH-USD." It is also the last of `notes`.
+   * For ethereum use ETH-USD." A live company that only shares the letters gets
+   * "Also a coin: LINK-USD" (`notTheCoinNote`). It is also the last of `notes`.
    */
   coinNote: string | null;
   /**
@@ -367,7 +368,7 @@ async function describeResolution(
   const formerIssuer = describeFormerIssuer(listing.symbol, payload, current);
   // One line: a company that left the symbol, else one that merged away from it.
   const line = tickerChangeLine(change) ?? formerIssuer?.note;
-  const coinNote = listing.exchange ? null : savedListingCoinNote(listing.symbol, resolved.ticker);
+  const coinNote = listing.exchange ? null : savedListingCoinNote(listing.symbol, resolved.ticker, { ended: !!resolved.ended });
   return { ...resolved, notes: [...line ? [line] : [], ...resolved.notes, ...coinNote ? [coinNote] : []], change, formerIssuer, coinNote,
     readAs: listing.readAs ?? null, bareSymbol: listing.exchange ? null : listing.symbol, otherVenues: resolved.otherVenues ?? null };
 }