gloomberb 0.18.2 → 0.18.3

package/src/telemetry/update-failures.ts

@@ -0,0 +1,307 @@
+import type { UpdateFailureReport } from "../api-client";
+import type { UpdateChannel } from "../types/config";
+import type { UpdateFailure } from "../updater/failure";
+import { logFailure } from "../utils/log-failure";
+import { compareSemver } from "../utils/semver";
+import { VERSION } from "../version";
+import { reportCrash, type CrashReportContext } from "./crash-reports";
+
+/**
+ * Failed update steps, sent to error tracking through the crash reporter (and
+ * so behind the same off switch). A report is the step, a fixed code, the
+ * versions, the channel, the platform and how the app was installed: never the
+ * error's text, which can hold a path, a user name or a signed URL.
+ *
+ * The process that runs the update reports it: the terminal app, and the
+ * desktop app's Bun process. The desktop view and the web install no host, so
+ * the same failure is never sent twice. One report per step, code and app
+ * version a day is enough to see a stuck updater; the hourly check that keeps
+ * failing offline adds nothing after the first.
+ *
+ * The desktop host also keeps what an install was about to do, so the next
+ * launch can tell an install that never took, or an update downloaded and
+ * then quit without, from one that worked (`reviewLastUpdateAttempt`).
+ */
+
+/**
+ * Where the running app sits. macOS installs replace the app bundle in place,
+ * which only works from a folder the user can write: not from a disk image,
+ * and not from the read-only copy App Translocation runs a quarantined app from.
+ */
+export type UpdateInstallKind =
+  | "desktop-applications"
+  | "desktop-translocated"
+  | "desktop-volume"
+  | "desktop-elsewhere"
+  /** Windows and Linux: the app folder the installer created. */
+  | "desktop-app-data"
+  | "terminal-binary"
+  | "terminal-managed"
+  | "terminal-package-manager"
+  | "terminal-source"
+  | "unknown";
+
+/** One update the app downloaded or started installing, and when. */
+export interface UpdateAttempt {
+  from: string;
+  to: string;
+  channel: UpdateChannel;
+  at: number;
+}
+
+/** What the host keeps on disk between launches. */
+export interface UpdateReportState {
+  /** When each step, code and app version was last reported, in ms. */
+  sent: Record<string, number>;
+  /** A downloaded update waiting for the user's Restart. */
+  staged?: UpdateAttempt;
+  /** An install the user started; the next launch says whether it took. */
+  applying?: UpdateAttempt;
+}
+
+export interface UpdateFailureReporterHost {
+  installKind: UpdateInstallKind;
+  /** The running version; defaults to this build's. */
+  appVersion?: string;
+  /** `process.platform` and `process.arch`. */
+  platform: string;
+  arch: string;
+  load(): UpdateReportState;
+  save(state: UpdateReportState): void;
+  now?(): number;
+  /** Defaults to the crash reporter. */
+  send?(report: UpdateFailureReport): void;
+}
+
+export interface UpdateFailureContext {
+  /** The version the update was going to, when one was known. */
+  targetVersion?: string | null;
+  channel?: UpdateChannel | null;
+}
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** Older attempts say nothing about this launch: the user installed by hand, or reinstalled. */
+const ATTEMPT_MAX_AGE_MS = 30 * DAY_MS;
+/**
+ * The install quits the app and opens the new one as soon as it is gone. A new
+ * version first seen this long after is one the user opened again by hand.
+ */
+const RELAUNCH_GRACE_MS = 10 * 60 * 1000;
+const VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]{1,60})?$/;
+
+let host: UpdateFailureReporterHost | null = null;
+
+function cleanVersion(value: string | null | undefined): string | undefined {
+  const version = value?.trim().replace(/^v/, "");
+  return version && VERSION_PATTERN.test(version) ? version : undefined;
+}
+
+function reportPlatform(platform: string): UpdateFailureReport["platform"] {
+  if (platform === "darwin") return "macos";
+  if (platform === "win32") return "windows";
+  if (platform === "linux") return "linux";
+  return "other";
+}
+
+function reportArch(arch: string): UpdateFailureReport["arch"] {
+  return arch === "arm64" || arch === "x64" ? arch : "other";
+}
+
+/**
+ * The report, from fixed values only: anything that is not a version, a
+ * known channel, platform or install kind is left out or named `other`.
+ */
+function buildUpdateFailureReport(
+  failure: UpdateFailure,
+  fields: UpdateFailureContext & {
+    appVersion: string;
+    platform: string;
+    arch: string;
+    installKind: UpdateInstallKind;
+  },
+): UpdateFailureReport {
+  const targetVersion = cleanVersion(fields.targetVersion);
+  return {
+    phase: failure.phase,
+    code: failure.code,
+    appVersion: cleanVersion(fields.appVersion) ?? "unknown",
+    ...(targetVersion ? { targetVersion } : {}),
+    channel: fields.channel === "nightly" ? "nightly" : "stable",
+    platform: reportPlatform(fields.platform),
+    arch: reportArch(fields.arch),
+    installKind: fields.installKind,
+  };
+}
+
+/**
+ * The report as the crash reporter sends it. Today's server keeps the error's
+ * type, message, plugin and pane: the message is the step and code, so error
+ * tracking groups one issue per failure, and the pane holds the rest as
+ * `key=value` pairs. The `update` field carries the same values for a server
+ * that reads it.
+ */
+function updateFailureCrashReport(report: UpdateFailureReport): {
+  error: { name: string; message: string };
+  context: CrashReportContext;
+} {
+  const details = [
+    `to=${report.targetVersion ?? "none"}`,
+    `channel=${report.channel}`,
+    `platform=${report.platform}-${report.arch}`,
+    `install=${report.installKind}`,
+  ].join(" ");
+  return {
+    // A plain object, not an Error: it has no stack, so no file path goes along.
+    error: { name: "UpdateFailed", message: `${report.phase}: ${report.code}` },
+    context: { kind: "plugin", plugin: "updater", pane: details, update: report },
+  };
+}
+
+function sendThroughCrashReporter(report: UpdateFailureReport): void {
+  const { error, context } = updateFailureCrashReport(report);
+  reportCrash(error, context);
+}
+
+/**
+ * Takes the day's slot for `key`, or says it is used: one report per step,
+ * code and version a day. Drops what is older than a day while at it.
+ */
+function takeReportSlot(state: UpdateReportState, key: string, now: number): boolean {
+  for (const [entry, at] of Object.entries(state.sent)) {
+    if (!(now - at < DAY_MS) || at > now) delete state.sent[entry];
+  }
+  if (state.sent[key] !== undefined) return false;
+  state.sent[key] = now;
+  return true;
+}
+
+function loadState(current: UpdateFailureReporterHost): UpdateReportState {
+  try {
+    const state = current.load();
+    return { ...state, sent: { ...state.sent } };
+  } catch (error) {
+    logFailure("telemetry-update-failures", "Could not read update report state")(error);
+    return { sent: {} };
+  }
+}
+
+function saveState(current: UpdateFailureReporterHost, state: UpdateReportState): void {
+  try {
+    current.save(state);
+  } catch (error) {
+    logFailure("telemetry-update-failures", "Could not save update report state")(error);
+  }
+}
+
+function sendIfDue(
+  current: UpdateFailureReporterHost,
+  state: UpdateReportState,
+  failure: UpdateFailure,
+  context: UpdateFailureContext,
+  now: number,
+): void {
+  const report = buildUpdateFailureReport(failure, {
+    ...context,
+    appVersion: current.appVersion ?? VERSION,
+    platform: current.platform,
+    arch: current.arch,
+    installKind: current.installKind,
+  });
+  if (!takeReportSlot(state, `${report.phase}|${report.code}|${report.appVersion}`, now)) return;
+  (current.send ?? sendThroughCrashReporter)(report);
+}
+
+export function installUpdateFailureReporter(next: UpdateFailureReporterHost): () => void {
+  host = next;
+  return () => {
+    if (host === next) host = null;
+  };
+}
+
+/** Reports one failed step. Never throws; does nothing where no host is installed. */
+export function reportUpdateFailure(failure: UpdateFailure, context: UpdateFailureContext = {}): void {
+  const current = host;
+  if (!current) return;
+  try {
+    const now = current.now?.() ?? Date.now();
+    const state = loadState(current);
+    // An install that failed in this run is reported here, not again at the next launch.
+    if (failure.phase === "apply" || failure.phase === "relaunch") delete state.applying;
+    sendIfDue(current, state, failure, context, now);
+    saveState(current, state);
+  } catch (error) {
+    logFailure("telemetry-update-failures", "Could not report update failure")(error);
+  }
+}
+
+function recordAttempt(field: "staged" | "applying", to: string, channel: UpdateChannel): void {
+  const current = host;
+  if (!current) return;
+  const state = loadState(current);
+  const attempt: UpdateAttempt = { from: current.appVersion ?? VERSION, to, channel, at: current.now?.() ?? Date.now() };
+  if (field === "applying") delete state.staged;
+  state[field] = attempt;
+  saveState(current, state);
+}
+
+/** A downloaded update is waiting for the user's Restart. */
+export function noteUpdateStaged(to: string, channel: UpdateChannel): void {
+  recordAttempt("staged", to, channel);
+}
+
+/** The user pressed Restart: the next launch should be `to`. */
+export function noteUpdateApplying(to: string, channel: UpdateChannel): void {
+  recordAttempt("applying", to, channel);
+}
+
+/** The waiting update was taken back (a channel switch); quitting without it is no longer news. */
+export function forgetStagedUpdate(): void {
+  const current = host;
+  if (!current) return;
+  const state = loadState(current);
+  if (!state.staged) return;
+  delete state.staged;
+  saveState(current, state);
+}
+
+/**
+ * Run once at launch: what came of the last update this app started.
+ *
+ * - Restarted into the new version: nothing to report, unless the new version
+ *   only came up long after, which is the app failing to reopen itself.
+ * - Still the old version after an install: it never took.
+ * - Still the old version with a download waiting: the app was quit without
+ *   restarting into it, which the stuck installs may come down to.
+ */
+export function reviewLastUpdateAttempt(): void {
+  const current = host;
+  if (!current) return;
+  const currentVersion = current.appVersion ?? VERSION;
+  try {
+    const state = loadState(current);
+    const { applying, staged } = state;
+    if (!applying && !staged) return;
+    delete state.applying;
+    delete state.staged;
+    const now = current.now?.() ?? Date.now();
+    const fresh = (attempt: UpdateAttempt | undefined) => !!attempt && now - attempt.at < ATTEMPT_MAX_AGE_MS && attempt.at <= now;
+    if (applying && fresh(applying)) {
+      const context = { targetVersion: applying.to, channel: applying.channel };
+      if (applying.from === currentVersion) {
+        sendIfDue(current, state, { phase: "apply", code: "not_applied" }, context, now);
+      } else if ((compareSemver(currentVersion, applying.to) ?? -1) >= 0 && now - applying.at > RELAUNCH_GRACE_MS) {
+        sendIfDue(current, state, { phase: "relaunch", code: "relaunch_missed" }, context, now);
+      }
+    } else if (staged && fresh(staged) && staged.from === currentVersion) {
+      sendIfDue(current, state, { phase: "apply", code: "not_restarted" }, { targetVersion: staged.to, channel: staged.channel }, now);
+    }
+    saveState(current, state);
+  } catch (error) {
+    logFailure("telemetry-update-failures", "Could not review the last update")(error);
+  }
+}
+
+/** Test seam. */
+export function resetUpdateFailureReporterForTests(): void {
+  host = null;
+}

package/src/tickers/company-name-listing.ts

@@ -2,7 +2,7 @@ import { logFailure } from "../utils/log-failure";
 import type { DataProvider } from "../types/data-provider";
 import type { InstrumentSearchResult } from "../types/instrument";
 import { canonicalExchange, isUsListingExchange, parsePublicTickerKey } from "../utils/exchanges";
-import { companyNameExtraWords, shortCompanyName } from "./company-name";
+import { companyNameMatch, shortCompanyName } from "./company-name";
 import { LISTING_SEARCH_LIMIT } from "./search";
 import { classifyInstrumentKind } from "./search/ranking";
 import { isProviderBusy, type ProviderBusyError } from "../sources/provider-errors";
@@ -28,10 +28,12 @@ export function isCompanyNameInput(input: string): boolean {
 /**
  * The listing a company's name stands for when it is typed where a symbol
  * goes, as an entry of a comma list ("Whirlpool Corporation" is WHR on
- * NYSE). Of search's listings whose names have every word of it (the name is
- * also searched without its legal form, which can find more), the company
+ * NYSE). Of search's listings whose names have every word of it, or a word
+ * it shortens ("philip morris intl" is Philip Morris International; the name
+ * is also searched without its legal form, which can find more), the company
  * whose name says no more than the one typed goes first, so a subsidiary that
- * shares the word (Whirlpool of India) does not; then its line on a US
+ * shares the word (Whirlpool of India) does not, and of those a name matched
+ * word for word before one a short form matched; then its line on a US
  * exchange, then a plain line before a depositary receipt, the shortest
  * symbol (WHR before WHR-A) and search's order. Contracts, preferred shares
  * and notes are never the listing. Null when none matches; when none does
@@ -55,10 +57,10 @@ export async function findListingOfCompanyName(
   const ranked = results.flatMap((result, order) => {
     const exchange = canonicalExchange(result.exchange === "SMART" ? result.primaryExchange : result.exchange || result.primaryExchange);
     const type = result.brokerContract?.secType || result.type || "";
-    const extra = companyNameExtraWords(name, result.name);
-    if (!exchange || extra == null || classifyInstrumentKind(type) === "derivative" || NOT_COMMON.test(type)
+    const match = companyNameMatch(name, result.name);
+    if (!exchange || match == null || classifyInstrumentKind(type) === "derivative" || NOT_COMMON.test(type)
       || parsePublicTickerKey(result.symbol).exchange) return [];
-    return [{ result, exchange, rank: [extra, isUsListingExchange(exchange) ? 0 : 1, RECEIPT.test(type) ? 1 : 0, result.symbol.length, order] }];
+    return [{ result, exchange, rank: [match.extra, match.abbreviated, isUsListingExchange(exchange) ? 0 : 1, RECEIPT.test(type) ? 1 : 0, result.symbol.length, order] }];
   }).sort((left, right) => {
     const at = left.rank.findIndex((value, index) => value !== right.rank[index]);
     return at < 0 ? 0 : left.rank[at]! - right.rank[at]!;

package/src/tickers/company-name.ts

@@ -56,6 +56,49 @@ export function companyNameExtraWords(typed: string, name: string | null | undef
   return words.size - wanted.size;
 }
 
+/**
+ * Whether a typed word is a short form of a name's word, as a list writes
+ * one: its first letter and the rest in order, at least three letters
+ * (`intl` for international, `hldgs` for holdings, `grp` for group).
+ */
+function abbreviates(short: string, word: string): boolean {
+  if (short.length < 3 || short.length >= word.length || short[0] !== word[0] || !/^\p{L}+$/u.test(short)) return false;
+  let at = 0;
+  for (const char of word) {
+    if (char === short[at]) at += 1;
+    if (at === short.length) return true;
+  }
+  return false;
+}
+
+/**
+ * `companyNameExtraWords` for a name typed with short forms, as a list or a
+ * spreadsheet writes it ("philip morris intl" for Philip Morris
+ * International Inc.): each typed word is one of the name's, or a short form
+ * of another of its words (`abbreviates`). `extra` counts the name's words
+ * left unmatched, `abbreviated` the typed words read as short forms, so an
+ * exact name ranks before one only a short form reaches. Null when a typed
+ * word is in the name neither way, or nothing was typed.
+ */
+export function companyNameMatch(typed: string, name: string | null | undefined): { extra: number; abbreviated: number } | null {
+  const wanted = companyWords(typed);
+  const words = companyWords(name);
+  if (wanted.size === 0) return null;
+  const matched = new Set<string>();
+  let abbreviated = 0;
+  for (const word of wanted) {
+    if (words.has(word)) {
+      matched.add(word);
+      continue;
+    }
+    const long = [...words].find((candidate) => !matched.has(candidate) && !wanted.has(candidate) && abbreviates(word, candidate));
+    if (!long) return null;
+    matched.add(long);
+    abbreviated += 1;
+  }
+  return { extra: words.size - matched.size, abbreviated };
+}
+
 /** Items grouped by the company their names are, in the order each company first appears. Unnamed items are left out. */
 export function groupByCompany<T>(items: readonly T[], nameOf: (item: T) => string | null | undefined): T[][] {
   const groups: T[][] = [];

package/src/tickers/listing-fate.ts

@@ -235,6 +235,36 @@ export function listingFateNotes(fate: ListingFate, served: { served: boolean; f
   ].filter((line): line is string => !!line);
 }
 
+/**
+ * A report's notes and errors beside what became of its symbol, worded as
+ * `quote`, `history` and `options` word it: with nothing served, the fate is
+ * why ("TWTR: Delisted Oct 27, 2022", "FB now lists ...; Meta Platforms
+ * trades as META") and stands in for the errors the empty load raised ("Not
+ * a ticker", "No options provider"); with data, `listingFateNotes` beside
+ * the errors. A symbol whose company moved, with nothing listed under it now,
+ * has nothing of its own to serve and throws `MovedSymbolError`.
+ */
+export function listingFateReport(
+  fate: ListingFate,
+  served: { served: boolean; firstDate?: string | null },
+  errors: readonly string[],
+): { notes: string[]; errors: string[] } {
+  if (fate.moved) throw new MovedSymbolError(fate.moved);
+  const notes = listingFateNotes(fate, served);
+  return { notes, errors: !served.served && notes.length > 0 ? [] : [...errors] };
+}
+
+/**
+ * A report that served nothing for its symbol (`listingFateReport`): what
+ * became of the symbol is the one reason it is empty, said once in place of
+ * every table's "No data." and of the load's errors; the errors alone when
+ * nothing became of it.
+ */
+export function listingFateEmpty(fate: ListingFate, errors: readonly string[]): { empty?: string; errors: string[] } {
+  const report = listingFateReport(fate, { served: false }, errors);
+  return report.notes.length ? { empty: report.notes.join(" "), errors: report.errors } : { errors: report.errors };
+}
+
 /**
  * What a report or loader with nothing of its own to serve for a symbol
  * throws when the symbol's company moved (`ListingFate.moved`): its message

package/src/types/data-provider.ts

@@ -16,6 +16,7 @@ import type { BrokerContractRef, InstrumentSearchResult } from "./instrument";
 import type { CachePolicyMap } from "./persistence";
 import type { CachedQueryHandle } from "../data/cached-query";
 import type { TickerChanges } from "./ticker-changes";
+import type { IssuerListings } from "./issuer-listings";
 
 export type CachedAssetMethod = "getExchangeRate" | "getHolders" | "getAnalystResearch" | "getCorporateActions"
   | "getOptionsChain" | "getSecFilings" | "getSecFilingDocuments" | "getSecFilingContent" | "getArticleSummary";
@@ -252,6 +253,11 @@ export interface AssetDataProvider {
    * answer for is left out; null when the source cannot answer a batch at all.
    */
   getTickerChangesBatch?(symbols: string[], options?: { signal?: AbortSignal }): Promise<Map<string, TickerChanges | null> | null>;
+  /**
+   * Every listing of the company a listing belongs to (RCI and RCI.B:TSX are
+   * Rogers). Null when the source does not hold the company.
+   */
+  getIssuerListings?(symbol: string, exchange?: string, options?: { signal?: AbortSignal }): Promise<IssuerListings | null>;
   /**
    * Several searches in a few requests, each answered with the rows `search`
    * gives it from this source (up to `limit`), by query as asked. A query the

package/src/types/headless.ts

@@ -542,6 +542,13 @@ export interface HeadlessPaneDefinition<Shape extends HeadlessPaneShape = Headle
   discovery?: {
     id?: string;
     aliases?: string[];
+    /**
+     * Words that are no function's code but ask for this function's data
+     * (IVOL, IV for implied volatility). They do not open it, since one word
+     * can mean several functions: `fn IVOL` answers with the functions it
+     * means and the commands that run them, and `catalog ivol` lists them first.
+     */
+    suggestFor?: string[];
     intents?: string[];
     dataRequirements?: string[];
     limitations?: string[];

package/src/types/issuer-listings.ts

@@ -0,0 +1,28 @@
+/**
+ * Every listing of one company, as Gloom Cloud's company universe groups
+ * them: share classes, a US receipt and its home line, dual listings. RCI on
+ * the NYSE and RCI.B on the TSX are both Rogers Communications.
+ */
+
+/** One listing, written as the service writes it: bare on a US venue (RCI), SYMBOL:EXCHANGE elsewhere (RCI.B:TSX). */
+interface IssuerListing {
+  symbol: string;
+  /** The canonical venue code. */
+  exchange: string;
+  name: string;
+  /** The company's primary line. */
+  primary: boolean;
+}
+
+export interface IssuerListings {
+  /** The service's key for the company (cik:733099). */
+  issuer: string;
+  name: string;
+  /**
+   * Where the company is from, ISO 3166 alpha-2: its primary line's country,
+   * or the SEC address of a foreign company whose only lines are in the US.
+   */
+  country: string;
+  /** The primary line first. */
+  listings: IssuerListing[];
+}

package/src/updater/failure.ts

@@ -0,0 +1,163 @@
+/**
+ * Why an update step failed, as a fixed phase and code rather than the error
+ * text: the header says the reason in a few words, and error tracking gets
+ * the same two values, which carry no path, URL or account name.
+ */
+
+/** The step that failed. `relaunch` is getting back into the app after an install. */
+export type UpdateFailurePhase = "check" | "download" | "verify" | "apply" | "relaunch";
+
+const UPDATE_FAILURE_CODES = [
+  /** No route to the release server: offline, DNS, refused, TLS. */
+  "offline",
+  "timeout",
+  /** GitHub answered 403 or 429, its limit for requests without an account. */
+  "rate_limited",
+  "server_error",
+  /** The release has no such file (404). */
+  "not_found",
+  /** Any other refusal from the release server. */
+  "http_error",
+  /** The release list or manifest did not read as one. */
+  "bad_response",
+  /** The release has no build for this platform, or none with a checksum. */
+  "no_build",
+  /** The download stopped before the whole file arrived. */
+  "interrupted",
+  /** The file arrived whole but does not match its checksum, or does not unpack. */
+  "corrupt",
+  "permission_denied",
+  /** The macOS app runs from where it cannot be replaced: a disk image, App Translocation, another volume. */
+  "wrong_location",
+  /** The downloaded update and the installed app are on different disks, so the one cannot be moved onto the other. */
+  "cross_device",
+  "read_only",
+  "disk_full",
+  /** Another process holds the files being replaced. */
+  "file_in_use",
+  /** The update downloaded earlier is no longer where the install expects it. */
+  "staged_missing",
+  /** A restart into the update came back on the old version. */
+  "not_applied",
+  /** The app quit with a downloaded update waiting and was opened again on the old version. */
+  "not_restarted",
+  /** The install finished but the app did not come back by itself. */
+  "relaunch_missed",
+  "unknown",
+] as const;
+
+export type UpdateFailureCode = typeof UPDATE_FAILURE_CODES[number];
+
+export interface UpdateFailure {
+  phase: UpdateFailurePhase;
+  code: UpdateFailureCode;
+}
+
+/** What an HTTP status from the release server means for an update. */
+export function httpStatusFailureCode(status: number): UpdateFailureCode {
+  if (status === 403 || status === 429) return "rate_limited";
+  if (status === 404 || status === 410) return "not_found";
+  if (status >= 500) return "server_error";
+  return "http_error";
+}
+
+const OFFLINE_ERRNO = new Set([
+  "ENOTFOUND",
+  "EAI_AGAIN",
+  "ECONNREFUSED",
+  "ENETUNREACH",
+  "EHOSTUNREACH",
+  "ENETDOWN",
+  // Bun's fetch
+  "ConnectionRefused",
+  "FailedToOpenSocket",
+  "UnableToConnect",
+  "CERT_HAS_EXPIRED",
+  "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
+  "SELF_SIGNED_CERT_IN_CHAIN",
+]);
+const INTERRUPTED_ERRNO = new Set(["ECONNRESET", "EPIPE", "ECONNABORTED", "ConnectionClosed"]);
+
+/**
+ * The code for an error a step threw, from its system error code first and its
+ * message second. Only the code leaves the machine; the message stays local.
+ */
+export function classifyUpdateError(error: unknown): UpdateFailureCode {
+  const record = (error && typeof error === "object" ? error : {}) as { code?: unknown; name?: unknown; message?: unknown };
+  const message = typeof record.message === "string" ? record.message : typeof error === "string" ? error : "";
+  // A system error code, or one named in the message ("Failed to replace app: EACCES: ...").
+  const errno = typeof record.code === "string" ? record.code : /\b(E[A-Z]{3,})\b/.exec(message)?.[1] ?? "";
+  switch (errno) {
+    case "EACCES":
+    case "EPERM":
+      return "permission_denied";
+    case "EROFS":
+      return "read_only";
+    case "ENOSPC":
+    case "EDQUOT":
+      return "disk_full";
+    case "EBUSY":
+    case "ETXTBSY":
+      return "file_in_use";
+    case "EXDEV":
+      return "cross_device";
+    case "ETIMEDOUT":
+      return "timeout";
+  }
+  if (OFFLINE_ERRNO.has(errno)) return "offline";
+  if (INTERRUPTED_ERRNO.has(errno)) return "interrupted";
+  if (record.name === "TimeoutError" || record.name === "AbortError") return "timeout";
+
+  const status = /\b(?:HTTP|returned|status|failed:?)\s*\(?(\d{3})\b/i.exec(message)?.[1];
+  if (status) return httpStatusFailureCode(Number(status));
+  if (/checksum mismatch|hash mismatch/i.test(message)) return "corrupt";
+  if (/zstd|decompress|gunzip|incorrect header|unexpected end of (?:file|data)/i.test(message)) return "corrupt";
+  if (/timed? ?out/i.test(message)) return "timeout";
+  if (/rate limit/i.test(message)) return "rate_limited";
+  if (/read-only file system/i.test(message)) return "read_only";
+  if (/cross-device/i.test(message)) return "cross_device";
+  if (/permission denied|operation not permitted|access is denied/i.test(message)) return "permission_denied";
+  if (/no space left|disk full/i.test(message)) return "disk_full";
+  if (/resource busy|text file busy|being used by another process/i.test(message)) return "file_in_use";
+  if (/connection (?:reset|closed|aborted)|socket hang up|premature close|terminated/i.test(message)) return "interrupted";
+  if (/unable to connect|fetch failed|failed to fetch|network|getaddrinfo|could not resolve|certificate/i.test(message)) return "offline";
+  if (/invalid update\.json|unexpected .*payload|json/i.test(message)) return "bad_response";
+  return "unknown";
+}
+
+/** When the failure has no more specific reason: what the step was. */
+const PHASE_REASONS: Record<UpdateFailurePhase, string> = {
+  check: "check failed",
+  download: "download failed",
+  verify: "could not verify the download",
+  apply: "could not install",
+  relaunch: "could not restart",
+};
+
+const CODE_REASONS: Partial<Record<UpdateFailureCode, string>> = {
+  offline: "no connection",
+  timeout: "connection timed out",
+  rate_limited: "GitHub rate limit",
+  server_error: "release server error",
+  not_found: "release server error",
+  http_error: "release server error",
+  bad_response: "unreadable release data",
+  no_build: "no build for this system",
+  interrupted: "download interrupted",
+  corrupt: "download corrupted",
+  permission_denied: "no permission to replace the app",
+  wrong_location: "move the app to Applications",
+  cross_device: "app and update on different disks",
+  read_only: "install folder is read-only",
+  disk_full: "disk full",
+  file_in_use: "app files in use",
+  staged_missing: "downloaded update missing",
+};
+
+/**
+ * The reason in a few words, in English (the caller translates it), sized
+ * for the header: "download interrupted", "no permission to replace the app".
+ */
+export function updateFailureReason(failure: UpdateFailure): string {
+  return CODE_REASONS[failure.code] ?? PHASE_REASONS[failure.phase];
+}