gloomberb 0.18.4 → 0.19.0

package/src/api-client/request.ts

@@ -1,6 +1,6 @@
 import { logFailure } from "../utils/log-failure";
 import { httpFetch, isHttpFetchStreaming } from "../utils/http-transport";
-import { withDeadline } from "../utils/async-deadline";
+import { OperationTimeoutError } from "../utils/async-deadline";
 import {
   ApiRequestError,
   parseApiErrorCode,
@@ -16,17 +16,59 @@ import {
   type ConnectionHealthRegistry,
 } from "../core/connection-health";
 import { SESSION_COOKIE_NAMES } from "./session-cookie";
-import { asDataServiceFailure } from "../utils/network-failure";
+import { asDataServiceFailure, DataServiceUnreachableError } from "../utils/network-failure";
 
 /** The public Gloom Cloud API, which the web app's same-origin `/api` path forwards to. */
 export const DEFAULT_API_URL = "https://api.gloom.sh";
+/**
+ * How long a request waits for the service to answer at all. Nothing back by
+ * then, and nothing else answered meanwhile, is a hung connection: the request
+ * fails as the data service being unreachable, as a refused one does.
+ */
 const DEFAULT_MARKET_REQUEST_TIMEOUT_MS = 10_000;
+/**
+ * A search, which a command and a keystroke wait on, gives up on a connection
+ * that sends nothing back sooner. A slow search on a service that answers
+ * (some take five seconds) still gets the full market deadline.
+ */
+const SEARCH_ANSWER_TIMEOUT_MS = 4_000;
+/**
+ * Once a request went unanswered, later ones wait this long for an answer,
+ * until any answer comes back: a hung connection is not waited out in full by
+ * every request a command or a pane makes after it.
+ */
+const UNREACHABLE_REQUEST_TIMEOUT_MS = 3_000;
+/**
+ * Right after a request hung with nothing back, the requests that follow it
+ * (a fallback, the next step of a command) fail at once rather than each
+ * waiting out a connection that just proved dead. Past this they try again.
+ */
+const HUNG_FAIL_FAST_MS = 5_000;
 const DEFAULT_RESEARCH_REQUEST_TIMEOUT_MS = 45_000;
+/** Requests outside market reads (saves, uploads, drafts) may take the server this long once it is known to answer. */
+const DEFAULT_SERVICE_REQUEST_LIMIT_MS = 120_000;
+const UPLOAD_REQUEST_LIMIT_MS = 300_000;
+/**
+ * How long the check that the service answers at all waits. It runs this long
+ * before a request's answer deadline, unless something answered meanwhile, so
+ * one slow request on a service that answers is waited for and a dead
+ * connection is not.
+ */
+const SERVICE_PROBE_TIMEOUT_MS = 3_000;
+const SERVICE_PROBE_PATH = "/health";
 // Research may fill missing sections after a primary read; quote/history reads remain latency bounded.
 const RESEARCH_MARKET_PATHS = new Set([
   "/market/dividends", "/market/short-interest", "/market/movers", "/market/trending",
   "/market/heatmap", "/market/earnings-calendar",
 ]);
+
+/** When a request gives up: without any answer from the service, and in all. */
+interface RequestDeadline {
+  answerMs: number;
+  limitMs: number;
+  /** When to check that the service answers at all, if nothing has by then; null when the deadline is too short for it. */
+  probeAtMs: number | null;
+}
 /** Local status for "this runtime cannot stream", never returned by the server. */
 export const STREAMING_UNSUPPORTED_STATUS = 0;
 
@@ -74,6 +116,8 @@ type CloudApiUploadTransport = (request: CloudApiUploadRequest) => Promise<Cloud
 let cloudApiFetchTransport: CloudApiFetchTransport = httpFetch;
 let cloudApiUploadTransport: CloudApiUploadTransport | null = null;
 let cloudApiTransportInstalled = false;
+/** Counts installed transports, so what a client learned of one connection is not applied to the next. */
+let cloudApiTransportGeneration = 0;
 let cloudApiFetchStreaming = true;
 let cloudApiStreamFetch: CloudApiStreamFetch | null = null;
 
@@ -83,6 +127,7 @@ export function setCloudApiFetchTransport(
 ): void {
   cloudApiFetchTransport = transport ?? httpFetch;
   cloudApiTransportInstalled = !!transport;
+  cloudApiTransportGeneration += 1;
   cloudApiFetchStreaming = transport ? (options.streaming ?? false) : true;
   cloudApiStreamFetch = transport ? options.streamFetch ?? null : null;
 }
@@ -163,22 +208,6 @@ function throwIfRequestAborted(signal: AbortSignal | null | undefined): void {
   );
 }
 
-/**
- * Sends one request, saying the same thing whichever fetch failed to connect
- * (Bun's "Unable to connect", a browser's "Failed to fetch", a refused proxy):
- * every command, pane and status line then reads "Gloom couldn't reach its
- * data service", and code that falls back to a saved copy can tell it apart.
- * A caller's abort stays an abort.
- */
-async function reachService<R>(fetch: () => Promise<R>, signal: AbortSignal | null | undefined): Promise<R> {
-  try {
-    return await fetch();
-  } catch (error) {
-    if (signal?.aborted) throw error;
-    throw asDataServiceFailure(error);
-  }
-}
-
 export class CloudApiRequestTransport {
   private sessionToken: string | null = null;
   private sessionCookieName: SessionCookieName | null = null;
@@ -188,6 +217,17 @@ export class CloudApiRequestTransport {
   private readonly marketRequestTimeoutMs: number;
   private readonly researchRequestTimeoutMs: number;
   private readonly connectionHealth: ConnectionHealthRegistry;
+  /** Answers received from the service, by any request: a request that sees this grow knows the connection works. */
+  private answers = 0;
+  /** The last request went unanswered (refused or hung) and nothing has answered since. */
+  private unreachable = false;
+  /** When a request last hung with nothing back, while nothing has answered since. */
+  private hungAt: number | null = null;
+  /** The installed transport the two above were learned on. */
+  private connectionGeneration = cloudApiTransportGeneration;
+  /** Requests waiting under a deadline: the check that the service answers runs only while one is. */
+  private pending = 0;
+  private probe: AbortController | null = null;
 
   readonly baseUrl = getCloudApiBaseUrl();
 
@@ -280,7 +320,7 @@ export class CloudApiRequestTransport {
       GLOOM_CLOUD_HTTP_CONNECTION_ID,
       operation,
       async () => {
-        const response = await reachService(() => streamFetch(`${this.baseUrl}${path}`, {
+        const response = await this.reachService(() => streamFetch(`${this.baseUrl}${path}`, {
           ...options,
           headers,
           credentials: "include",
@@ -301,37 +341,178 @@ export class CloudApiRequestTransport {
   }
 
   async request<T>(path: string, options?: RequestInit, canApplySession: () => boolean = () => true): Promise<T> {
-    if (!path.startsWith("/market/")) {
-      return this.performRequest<T>(path, options, canApplySession);
-    }
+    return this.withDeadline(path, this.deadlineFor(path), options?.signal, (signal) => this.performRequest<T>(path, {
+      ...options,
+      signal,
+    }, canApplySession));
+  }
 
-    const timeoutMs = RESEARCH_MARKET_PATHS.has(path.split("?")[0]!)
-      ? this.researchRequestTimeoutMs : this.marketRequestTimeoutMs;
+  /**
+   * Every request's deadline. A market read or a search waits about ten
+   * seconds, research and requests outside market data longer. With nothing
+   * back from the service, a request gives up at ten seconds, a search at
+   * four, and any request at three after one went unanswered, until something
+   * answers again. Three seconds before that, a request still unanswered
+   * checks that the service answers at all, so one slow request on a working
+   * connection is waited for and a dead connection is not.
+   */
+  private deadlineFor(path: string, limitMs?: number): RequestDeadline {
+    this.forgetOtherTransport();
+    const pathname = path.split("?")[0]!;
+    const market = pathname.startsWith("/market/");
+    const limit = limitMs ?? (!market ? DEFAULT_SERVICE_REQUEST_LIMIT_MS
+      : RESEARCH_MARKET_PATHS.has(pathname) ? this.researchRequestTimeoutMs : this.marketRequestTimeoutMs);
+    let answerMs = pathname === "/market/search"
+      ? Math.min(this.marketRequestTimeoutMs, SEARCH_ANSWER_TIMEOUT_MS)
+      : this.marketRequestTimeoutMs;
+    if (this.unreachable) answerMs = Math.min(answerMs, UNREACHABLE_REQUEST_TIMEOUT_MS);
+    return {
+      answerMs,
+      limitMs: Math.max(limit, answerMs),
+      probeAtMs: answerMs >= SERVICE_PROBE_TIMEOUT_MS ? answerMs - SERVICE_PROBE_TIMEOUT_MS : null,
+    };
+  }
+
+  /**
+   * Runs one request under its deadline. Without an answer from the service by
+   * `answerMs` (from this request, any other, or the check that the service
+   * answers at all), the connection is taken as hung: the request is aborted
+   * and fails as the data service being unreachable, as a refused connection
+   * does. A service that answers but is slow gets until `limitMs`, then the
+   * request times out. A caller's abort stays an abort.
+   */
+  private async withDeadline<T>(
+    path: string,
+    deadline: RequestDeadline,
+    callerSignal: AbortSignal | null | undefined,
+    run: (signal: AbortSignal) => Promise<T>,
+  ): Promise<T> {
     const controller = new AbortController();
-    const callerSignal = options?.signal;
     const abortFromCaller = () => controller.abort(callerSignal?.reason);
     if (callerSignal?.aborted) {
       abortFromCaller();
     } else {
       callerSignal?.addEventListener("abort", abortFromCaller, { once: true });
     }
-
+    const answersAtStart = this.answers;
+    const answered = () => this.answers > answersAtStart;
+    const generation = cloudApiTransportGeneration;
+    const what = path.startsWith("/market/") ? "Cloud market request" : "Cloud request";
+    const timedOut = (ms: number) => new OperationTimeoutError(`${what} timed out after ${ms}ms: ${path.split("?")[0]}`);
+    const timers: Array<ReturnType<typeof setTimeout>> = [];
+    if (this.hungAt != null && Date.now() - this.hungAt < HUNG_FAIL_FAST_MS && !controller.signal.aborted) {
+      callerSignal?.removeEventListener("abort", abortFromCaller);
+      throw new DataServiceUnreachableError(new OperationTimeoutError(`${what} not sent: the last one got no answer: ${path.split("?")[0]}`));
+    }
+    this.pending += 1;
     try {
-      const request = this.performRequest<T>(path, {
-        ...options,
-        signal: controller.signal,
-      }, canApplySession);
-      return await withDeadline(
-        request,
-        timeoutMs,
-        `Cloud market request timed out after ${timeoutMs}ms: ${path}`,
-        (error) => controller.abort(error),
-      );
+      const work = run(controller.signal);
+      return await new Promise<T>((resolve, reject) => {
+        const fail = (error: Error) => {
+          reject(error);
+          controller.abort(error);
+        };
+        work.then(resolve, reject);
+        if (deadline.probeAtMs != null) {
+          timers.push(setTimeout(() => {
+            if (!answered()) this.checkServiceAnswers();
+          }, deadline.probeAtMs));
+        }
+        timers.push(setTimeout(() => {
+          // The caller gave up first: its abort settles the request, and says nothing of the connection.
+          if (callerSignal?.aborted) return;
+          if (!answered()) {
+            this.recordNoAnswer(generation, true);
+            fail(new DataServiceUnreachableError(timedOut(deadline.answerMs)));
+          } else if (deadline.limitMs > deadline.answerMs) {
+            timers.push(setTimeout(() => fail(timedOut(deadline.limitMs)), deadline.limitMs - deadline.answerMs));
+          } else {
+            fail(timedOut(deadline.answerMs));
+          }
+        }, deadline.answerMs));
+      });
     } finally {
+      for (const timer of timers) clearTimeout(timer);
       callerSignal?.removeEventListener("abort", abortFromCaller);
+      this.pending -= 1;
+      // Nothing waits on the check any more: it must not hold a command's process open.
+      if (this.pending === 0) this.probe?.abort();
     }
   }
 
+  /**
+   * Sends one request, saying the same thing whichever fetch failed to connect
+   * (Bun's "Unable to connect", a browser's "Failed to fetch", a refused proxy):
+   * every command, pane and status line then reads "Gloom couldn't reach its
+   * data service", and code that falls back to a saved copy can tell it apart.
+   * A caller's abort stays an abort. An answer of any status says the
+   * connection works, for the deadlines of the requests beside it.
+   */
+  private async reachService<R>(fetch: () => Promise<R>, signal: AbortSignal | null | undefined): Promise<R> {
+    const generation = cloudApiTransportGeneration;
+    let response: R;
+    try {
+      response = await fetch();
+    } catch (error) {
+      if (signal?.aborted) throw error;
+      const failure = asDataServiceFailure(error);
+      if (failure instanceof DataServiceUnreachableError) this.recordNoAnswer(generation, false);
+      throw failure;
+    }
+    this.recordAnswer();
+    return response;
+  }
+
+  /** A new transport installed is a new connection: what failed on the last one says nothing about it. */
+  private forgetOtherTransport(): void {
+    if (this.fetchTransport || this.connectionGeneration === cloudApiTransportGeneration) return;
+    this.connectionGeneration = cloudApiTransportGeneration;
+    this.unreachable = false;
+    this.hungAt = null;
+  }
+
+  /** Something came back from the service: the connection works. */
+  private recordAnswer(): void {
+    this.answers += 1;
+    this.unreachable = false;
+    this.hungAt = null;
+  }
+
+  /**
+   * A request sent on the transport installed as `generation` got no answer:
+   * refused, or `hung` with nothing back by its deadline. Once another
+   * transport is installed, what one sent on the last says nothing of it.
+   */
+  private recordNoAnswer(generation: number, hung: boolean): void {
+    if (!this.fetchTransport && generation !== cloudApiTransportGeneration) return;
+    this.unreachable = true;
+    if (hung) this.hungAt = Date.now();
+  }
+
+  /**
+   * Asks the service for anything at all, once at a time, so a request that
+   * is slow can tell a slow server (which answers this) from a dead
+   * connection (which does not). Any status counts as an answer. It stops
+   * when nothing waits on it any more.
+   */
+  private checkServiceAnswers(): void {
+    if (this.probe) return;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), SERVICE_PROBE_TIMEOUT_MS);
+    const done = () => {
+      clearTimeout(timer);
+      if (this.probe === controller) this.probe = null;
+    };
+    // Done once given up on, even through a transport that ignores the abort.
+    controller.signal.addEventListener("abort", done, { once: true });
+    this.probe = controller;
+    (this.fetchTransport ?? cloudApiFetchTransport)(`${this.baseUrl}${SERVICE_PROBE_PATH}`, { signal: controller.signal })
+      .then(() => this.recordAnswer(), () => {
+        // Intentional ignore: an unanswered check only leaves the request it guards to its own deadline.
+      })
+      .finally(done);
+  }
+
   /**
    * POSTs raw bytes, such as an image, and parses the JSON answer like
    * `request`. Progress is reported where the installed upload transport can
@@ -355,17 +536,17 @@ export class CloudApiRequestTransport {
         url,
         body,
         headers: new Headers(init?.headers),
-        signal: options.signal,
+        signal: init?.signal ?? options.signal,
         onProgress: options.onProgress,
       })
       : undefined;
-    return this.performRequest<T>(path, {
+    return this.withDeadline(path, this.deadlineFor(path, UPLOAD_REQUEST_LIMIT_MS), options.signal, (signal) => this.performRequest<T>(path, {
       method: "POST",
       headers,
       // Typed arrays are valid fetch bodies; RequestInit's DOM typing lags behind.
       body: body as BodyInit,
-      signal: options.signal,
-    }, () => true, send);
+      signal,
+    }, () => true, send));
   }
 
   private async performRequest<T>(
@@ -389,7 +570,7 @@ export class CloudApiRequestTransport {
 
     const operation = `${options?.method ?? "GET"} ${path.split("?")[0]}`;
     const request = async () => {
-      const res = await reachService(() => (send ?? this.fetchTransport ?? cloudApiFetchTransport)(
+      const res = await this.reachService(() => (send ?? this.fetchTransport ?? cloudApiFetchTransport)(
         `${this.baseUrl}${path}`,
         {
           ...options,

package/src/api-client/research-activity.ts

@@ -29,10 +29,7 @@ export type ResearchActivity =
   | "onboarding_signed_in"
   | "onboarding_pro_viewed"
   | "onboarding_completed"
-  | "onboarding_skipped"
-  // The first action of a web visitor counted in the first-screen experiment,
-  // in that first session. Keep in sync with the server's list.
-  | "first_screen_engaged";
+  | "onboarding_skipped";
 export type ResearchFeature =
   | "overview"
   | "chart"
@@ -49,8 +46,9 @@ const signinWallExperiment = createWallExperimentSession("wall_teaser_signin");
 const upgradeExperiment = createUpgradeExperimentSession();
 const WALL_VIEWS_SESSION_KEY = "gloomberb.wall-teaser.views";
 
-const ATTRIBUTION_STORAGE_KEY = "gloomberb.web.attribution";
-const ANONYMOUS_ID_STORAGE_KEY = "gloomberb.web.anonymous-id";
+// The desktop app also keeps a copy of these two on disk (electrobun/view/view-ids.ts).
+export const ATTRIBUTION_STORAGE_KEY = "gloomberb.web.attribution";
+export const ANONYMOUS_ID_STORAGE_KEY = "gloomberb.web.anonymous-id";
 const HANDOFF_ID_KEY = "_gloom";
 const ATTRIBUTION_WINDOW_MS = 30 * 24 * 60 * 60 * 1000;
 /** Another device's clock may run slightly ahead; a touch from a minute in the future is still fresh. */
@@ -461,10 +459,7 @@ function webExperimentAttribution(): { experiments?: string } {
  * visitors on term.gloom.sh with an analytics id (no Do Not Track or Global
  * Privacy Control) and not driven by automation are asked. See web-experiments.ts.
  */
-export function exposeWebExperiment(
-  experiment: string,
-  { placement, signal }: { placement?: string; signal?: AbortSignal } = {},
-): Promise<string | null> {
+export function exposeWebExperiment(experiment: string): Promise<string | null> {
   if (!researchTelemetryAllowed()) return Promise.resolve(null);
   if (getCurrentPluginTarget() !== "web") return Promise.resolve(null);
   try {
@@ -481,8 +476,7 @@ export function exposeWebExperiment(
         attribution: attributionPayload(),
         experiment: key,
         variant,
-        ...(placement && ACTIVITY_ID.test(placement) ? { placement } : {}),
-      }, signal),
+      }),
     });
   } catch {
     return Promise.resolve(null);

package/src/api-client/types.ts

@@ -516,6 +516,18 @@ export interface CloudEconEventPayload {
   referencePeriod?: string | null;
   /** Who publishes the release (Freddie Mac for the 30-year mortgage rate), and its page when one is named. */
   source?: { name: string; url?: string };
+  /**
+   * The indicator this release is of, the same from one release to the next
+   * (`us-unemployment-rate` on every month's row), where `id` names the one
+   * row. Absent from a server that names none; exports leave the column empty.
+   */
+  indicatorId?: string | null;
+  /**
+   * Where the forecast (the consensus) was read from, `week-feed` or
+   * `release-calendar`, and when that feed was read. Absent on a row with no
+   * forecast and on one kept before the read was recorded.
+   */
+  consensus?: { source: string; readAt: string } | null;
 }
 
 /** One currency's short-term rate, as GET /cloud/econ/short-rates serves it. */
@@ -885,6 +897,13 @@ export interface CloudEarningsCallPayload {
    * New York day). Absent from a server that predates it.
    */
   callTimeKnown?: boolean;
+  /**
+   * "other" for an event that is not an earnings call (a deal call, a
+   * conference, an investor day), named by eventLabel and with no fiscal
+   * period; null when unclear. Older servers omit both.
+   */
+  eventKind?: "earnings" | "other" | null;
+  eventLabel?: string | null;
 }
 
 interface CloudJobsSeriesPoint {
@@ -1249,6 +1268,13 @@ export interface CloudEarningsTranscriptPayload {
   companyName: string | null;
   fiscalYear: number | null;
   fiscalQuarter: number | null;
+  /**
+   * "other" for an event that is not an earnings call (a deal call, a
+   * conference, an investor day), named by eventLabel and with no fiscal
+   * period; null when unclear. Older servers omit both.
+   */
+  eventKind?: "earnings" | "other" | null;
+  eventLabel?: string | null;
   callAt: string | null;
   timing: string | null;
   webcastUrl: string | null;
@@ -1530,6 +1556,8 @@ export interface CloudNewsPayload {
 export interface CloudNewsListResponse {
   items: CloudNewsPayload[];
   nextCursor: string | null;
+  /** Which news the service answered with, when it says: the live wire, or the one held back for a free account. */
+  access?: "realtime" | "delayed";
 }
 
 interface CloudTweetUserPayload {
@@ -1733,6 +1761,14 @@ export interface CloudMarketScreenerItem extends CloudMoverSessionFields {
   exchange: string;
   lastUpdated: number;
   dataSource: "live";
+  /** The listing's float as the equity screener serves it; absent where it serves none. */
+  floatShares?: number;
+  /** Set with a float the source states no measurement date for: `partial`. */
+  floatSharesState?: "partial";
+  /** Why the float is partial, as the server says it. */
+  floatSharesReason?: string;
+  /** When the statistics the float is read from were retrieved (ISO). */
+  floatSharesRetrievedAt?: string;
 }
 
 export interface CloudMarketScreenerPayload {
@@ -1927,6 +1963,44 @@ export interface ScannerFlowHistoryPage {
   hasMore: boolean;
 }
 
+/**
+ * Premium of a slice of the session's recorded prints by where it traded: at
+ * or above the ask (bought) or at or below the bid (sold). Mid and unknown
+ * prints count as neither.
+ */
+interface ScannerFlowSidePremium {
+  callAsk: number;
+  callBid: number;
+  putAsk: number;
+  putBid: number;
+}
+
+/** The session's prints in one time bucket, which starts at `at`. */
+export interface ScannerFlowSessionBucket extends ScannerFlowSidePremium {
+  at: number;
+}
+
+/** What one name printed at one expiry and strike during the session. */
+export interface ScannerFlowSessionStrike extends ScannerFlowSidePremium {
+  expiry: string;
+  strike: number;
+  /** Every call print's premium, mid and unknown included. */
+  callPremium: number;
+  putPremium: number;
+  prints: number;
+}
+
+/** The latest session's recorded prints under the FLOW pane's filters, summed. */
+export interface ScannerFlowSession {
+  /** The New York date of the session; null before any print was recorded. */
+  session: string | null;
+  bucketMs: number;
+  /** Buckets with a matching print, oldest first. */
+  buckets: ScannerFlowSessionBucket[];
+  /** Only when one name was asked for: most premium first. */
+  strikes: ScannerFlowSessionStrike[] | null;
+}
+
 export type ScannerPayload = ScannerHiloPayload | ScannerFlowPayload;
 
 /** What a scanner subscriber receives: data, or the entitlement refusal. */

package/src/app/keybindings/index.ts

@@ -14,6 +14,7 @@ export {
   type KeyChordEventLike,
 } from "./chord";
 export {
+  coreActionOnChord,
   describeKeybindingIssue,
   isPaneKeybindingAction,
   keyChordsOverlap,
@@ -32,6 +33,8 @@ export {
   formatChordForHost,
   menuAcceleratorFor,
   primaryModifierFor,
+  shortActionLabel,
+  takenChordMessage,
 } from "./labels";
 export { KeybindingsProvider, getDefaultKeybindings, useKeybindings, useResolvedKeybindings } from "./react";
 export {

package/src/app/keybindings/labels.ts

@@ -3,8 +3,9 @@ import {
   type ShortcutDisplayMode,
   type ShortcutPlatform,
 } from "../../utils/shortcut-labels";
+import { t, tf } from "../../i18n";
 import { formatKeyChord, serializeKeyChord, type KeyChord, type PrimaryModifier } from "./chord";
-import type { ResolvedKeybindings } from "./resolve";
+import type { ResolvedKeybindingAction, ResolvedKeybindings } from "./resolve";
 
 /** What `CmdOrCtrl` is on this host: Control in a terminal, Command on a Mac desktop. */
 export function primaryModifierFor(
@@ -85,3 +86,19 @@ export function menuAcceleratorFor(resolved: ResolvedKeybindings, actionId: stri
   const chord = resolved.actionsById.get(actionId)?.chords.find((entry) => entry.primary || entry.cmd);
   return chord ? serializeKeyChord(chord) : undefined;
 }
+
+/** The first clause of a description, for messages that name an action mid-sentence. */
+export function shortActionLabel(description: string): string {
+  const clause = description.split(/[,.](?:\s|$)/)[0] ?? description;
+  return clause.trim() || description.trim();
+}
+
+/**
+ * Why a chord a built-in action uses (coreActionOnChord) is refused, the
+ * same in the shortcuts editor and `config set keybindings`: "Ctrl+P is
+ * taken: Open the command bar. Press another key."
+ */
+export function takenChordMessage(chord: string, action: ResolvedKeybindingAction): string {
+  const name = action.def ? t(action.def.description) : action.pluginShortcut?.description ?? action.id;
+  return tf("{chord} is taken: {target}. Press another key.", { chord, target: shortActionLabel(name) });
+}

package/src/app/keybindings/resolve.ts

@@ -249,6 +249,20 @@ export function matchKeybinding(resolved: ResolvedKeybindings, event: KeyChordEv
   return null;
 }
 
+/**
+ * The built-in action already on a chord, on this host, other than `exceptId`:
+ * one whose chord fires on the same keypress, a digit under the layout
+ * switcher's 1-9 included. Capture refuses such a chord, so a new binding never
+ * leaves a core key (the command bar, close pane, quit) dead. Null when no
+ * built-in action has it; a plugin shortcut or a bound command does not count.
+ */
+export function coreActionOnChord(resolved: ResolvedKeybindings, chord: KeyChord, exceptId?: string): ResolvedKeybindingAction | null {
+  return resolved.actions.find((action) => action.def && action.id !== exceptId
+    && action.chords.some((existing) => keyChordsOverlap(existing, chord)
+      || (existing.key === "digit" && /^[1-9]$/.test(chord.key) && keyChordsOverlap({ ...existing, key: chord.key }, chord))))
+    ?? null;
+}
+
 export function matchesKeybindingAction(resolved: ResolvedKeybindings, id: string, event: KeyChordEventLike): boolean {
   const action = resolved.actionsById.get(id);
   return !!action && action.chords.some((chord) => matchesKeyChord(chord, event));

package/src/app/pane-runtime/plugin-bindings.ts

@@ -513,13 +513,17 @@ export function bindAppPanePluginRegistry({
       removeExternalPlugin(pluginId, directory);
     },
     contributions: (pluginId) => {
+      // An unlisted function (`listed: false`) and a pane only it opens are left out, as of every list.
+      const registered = pluginRegistry.getPluginPaneTemplateIds(pluginId)
+        .map((id) => ({ id, template: pluginRegistry.paneTemplates.get(id) }));
+      const listedPaneIds = new Set(registered.flatMap(({ template }) => template && template.listed !== false ? [template.paneId] : []));
+      const unlistedPaneIds = new Set(registered.flatMap(({ template }) => template?.listed === false && !listedPaneIds.has(template.paneId) ? [template.paneId] : []));
       const panes = pluginRegistry.getPluginPaneIds(pluginId)
+        .filter((id) => !unlistedPaneIds.has(id))
         .map((id) => ({ id, name: pluginRegistry.panes.get(id)?.name ?? id }));
-      const templates = pluginRegistry.getPluginPaneTemplateIds(pluginId)
-        .map((id) => {
-          const template = pluginRegistry.paneTemplates.get(id);
-          return { id, label: template?.label ?? id, ...(template?.shortcut?.prefix ? { prefix: template.shortcut.prefix } : {}) };
-        });
+      const templates = registered
+        .filter(({ template }) => template?.listed !== false)
+        .map(({ id, template }) => ({ id, label: template?.label ?? id, ...(template?.shortcut?.prefix ? { prefix: template.shortcut.prefix } : {}) }));
       const commands = [...pluginRegistry.commands.entries()]
         .filter(([id]) => pluginRegistry.getCommandPluginId(id) === pluginId && !id.endsWith(":setup"))
         .map(([id, command]) => ({ id, label: command.label, ...(command.shortcut ? { shortcut: command.shortcut } : {}) }));