gloomberb 0.15.2 → 0.15.4

package/src/state/hooks/quote-streaming.ts

@@ -6,9 +6,9 @@ import { debugLog } from "../../utils/debug-log";
 import { normalizeSymbol } from "../../utils/exchanges";
 import { getSharedMarketDataCoordinator, type MarketDataCoordinator } from "../../market-data/coordinator";
 import { useQuoteEntries } from "../../market-data/hooks";
-import type { InstrumentRef } from "../../market-data/request-types";
 import type { QueryEntry } from "../../market-data/result-types";
-import { buildInstrumentKey, buildQuoteKey } from "../../market-data/selectors";
+import { buildQuoteKey, instrumentFromQuoteTarget, uniqueQuoteInstruments } from "../../market-data/selectors";
+import { instrumentIdentityKey } from "../../utils/instrument-identity";
 
 const quoteStreamLog = debugLog.createLogger("quote-stream");
 export const DEFAULT_QUOTE_POLL_INTERVAL_MS = 60_000;
@@ -40,6 +40,13 @@ export function normalizeQuoteStreamSubscriptionTarget(target: QuoteSubscription
   };
 }
 
+function normalizeQuoteStreamSubscriptionTargets(targets: QuoteSubscriptionTarget[]): QuoteSubscriptionTarget[] {
+  return targets.flatMap((target) => {
+    const normalized = normalizeQuoteStreamSubscriptionTarget(target);
+    return normalized ? [normalized] : [];
+  });
+}
+
 /** The same target, ranked as off screen: not visible, not selected, low weight. */
 function downgradeOffscreenQuoteTarget(target: QuoteSubscriptionTarget): QuoteSubscriptionTarget {
   const weight = Number.isFinite(target.weight)
@@ -50,11 +57,7 @@ function downgradeOffscreenQuoteTarget(target: QuoteSubscriptionTarget): QuoteSu
 }
 
 export function buildQuoteStreamSubscriptionIdentityKey(target: QuoteSubscriptionTarget): string {
-  return `${buildInstrumentKey({
-    symbol: target.symbol, exchange: target.exchange,
-    brokerId: target.context?.brokerId, brokerInstanceId: target.context?.brokerInstanceId,
-    instrument: target.context?.instrument,
-  })}|${target.route ?? "auto"}`;
+  return `${instrumentIdentityKey(instrumentFromQuoteTarget(target))}|${target.route ?? "auto"}`;
 }
 
 export function buildQuoteStreamSubscriptionKey(target: QuoteSubscriptionTarget): string {
@@ -82,13 +85,7 @@ interface ActiveQuoteSubscription {
 
 function toCoordinatorQuoteTargets(targets: QuoteSubscriptionTarget[]): CoordinatorQuoteTargets {
   return targets.map((target) => ({
-    instrument: {
-      symbol: target.symbol,
-      exchange: target.exchange,
-      brokerId: target.context?.brokerId,
-      brokerInstanceId: target.context?.brokerInstanceId,
-      instrument: target.context?.instrument ?? null,
-    },
+    instrument: instrumentFromQuoteTarget(target),
     priority: {
       route: target.route,
       surface: target.surface,
@@ -211,34 +208,12 @@ export function useQuoteUpdates(
 ): void {
   const appActive = useAppVisible();
   const coordinator = getSharedMarketDataCoordinator();
-  const normalizedTargets = targets.flatMap((target) => {
-    const normalized = normalizeQuoteStreamSubscriptionTarget(target);
-    return normalized ? [normalized] : [];
-  });
+  const normalizedTargets = normalizeQuoteStreamSubscriptionTargets(targets);
   const instrumentKey = normalizedTargets
-    .map((target) => buildQuoteKey({
-      symbol: target.symbol,
-      exchange: target.exchange,
-      brokerId: target.context?.brokerId,
-      brokerInstanceId: target.context?.brokerInstanceId,
-      instrument: target.context?.instrument ?? null,
-    }))
+    .map((target) => buildQuoteKey(instrumentFromQuoteTarget(target)))
     .sort()
     .join("\u001f");
-  const instruments = useMemo(() => {
-    const unique = new Map<string, InstrumentRef>();
-    for (const target of normalizedTargets) {
-      const instrument: InstrumentRef = {
-        symbol: target.symbol,
-        exchange: target.exchange,
-        brokerId: target.context?.brokerId,
-        brokerInstanceId: target.context?.brokerInstanceId,
-        instrument: target.context?.instrument ?? null,
-      };
-      unique.set(buildQuoteKey(instrument), instrument);
-    }
-    return [...unique.values()];
-  }, [instrumentKey]);
+  const instruments = useMemo(() => uniqueQuoteInstruments(normalizedTargets), [instrumentKey]);
 
   useQuoteStreaming(targets, { enabled: liveStreaming });
 
@@ -295,10 +270,7 @@ export function useLiveQuoteEntries(
   subscriptionStartedAt: number;
 } {
   const appActive = useAppVisible();
-  const normalizedTargets = targets.flatMap((target) => {
-    const normalized = normalizeQuoteStreamSubscriptionTarget(target);
-    return normalized ? [normalized] : [];
-  });
+  const normalizedTargets = normalizeQuoteStreamSubscriptionTargets(targets);
   const targetKey = [...new Set(
     normalizedTargets.map((target) => buildQuoteStreamSubscriptionIdentityKey(target)),
   )]
@@ -318,20 +290,7 @@ export function useLiveQuoteEntries(
     };
   }
   const [freshnessNow, setFreshnessNow] = useState(() => Date.now());
-  const instruments = useMemo(() => {
-    const unique = new Map<string, InstrumentRef>();
-    for (const target of normalizedTargets) {
-      const instrument: InstrumentRef = {
-        symbol: target.symbol,
-        exchange: target.exchange,
-        brokerId: target.context?.brokerId,
-        brokerInstanceId: target.context?.brokerInstanceId,
-        instrument: target.context?.instrument ?? null,
-      };
-      unique.set(buildQuoteKey(instrument), instrument);
-    }
-    return [...unique.values()];
-  }, [targetKey]);
+  const instruments = useMemo(() => uniqueQuoteInstruments(normalizedTargets), [targetKey]);
 
   // The freshness clock only drives labels, so it stops while the pane is covered.
   const paneInView = usePaneInView();

package/src/state/hooks/session-snapshot.ts

@@ -69,7 +69,6 @@ export function usePersistSessionSnapshot(
         statusBarVisible: currentState.statusBarVisible,
         recentTickers: currentState.recentTickers,
         tickers: currentState.tickers,
-        exchangeRates: currentState.exchangeRates,
       }) satisfies AppSessionSnapshot;
     } catch {
       // Snapshot persistence is best-effort during teardown.

package/src/state/pane-scroll-registry.tsx

@@ -70,6 +70,15 @@ function scrollTargetByDelta(scrollBox: ScrollBoxRenderable, delta: number): num
   return target == null || target === scrollBox.scrollTop ? null : target;
 }
 
+/**
+ * Moves a scroll box by whole lines, kept within its content. For bodies that
+ * step one line per key, where the pane scroll keys would move a quarter page.
+ */
+export function scrollByLines(scrollBox: ScrollBoxRenderable, delta: number): void {
+  const target = scrollTargetByDelta(scrollBox, delta);
+  if (target != null) scrollBox.scrollTop = target;
+}
+
 function arrowScrollLines(scrollBox: ScrollBoxRenderable): number {
   return Math.max(MIN_ARROW_SCROLL_LINES, Math.floor((scrollBox.viewport?.height ?? 0) / 4));
 }

package/src/sync/controller.ts

@@ -1,7 +1,8 @@
 import type { Dispatch } from "react";
 import type { AppAction, AppState } from "../core/state/app/state";
 import type { AppTickerRepositoryPort } from "../core/app-service-ports";
-import { stableStringify } from "../remote/revision";
+import { stableStringify } from "../utils/hash";
+import { VERSION } from "../version";
 import {
   SYNC_SNAPSHOT_SCHEMA_VERSION,
   type RegisteredSyncContributor,
@@ -313,6 +314,7 @@ export class CloudSyncController {
       appId: "gloomberb",
       clientId: this.clientId ??= resolveClientId(),
       createdAt,
+      appVersion: VERSION,
       contributors: payloads,
     };
   }

package/src/sync/core-contributors.ts

@@ -1,6 +1,6 @@
 import { scheduleConfigSave } from "../state/config-save-scheduler";
 import { debugLog } from "../utils/debug-log";
-import { stableStringify } from "../remote/revision";
+import { stableStringify } from "../utils/hash";
 import type { AppConfig, BrokerInstanceConfig, SavedLayout } from "../types/config";
 import type { PricePoint, TickerFinancials } from "../types/financials";
 import type { Portfolio, TickerMetadata, TickerPosition, TickerRecord, Watchlist } from "../types/ticker";
@@ -8,6 +8,7 @@ import type { BrokerAccount } from "../types/trading";
 import { hydrateTickerMetadata } from "../tickers/metadata";
 import type { SyncContributor } from "./types";
 import { convertCurrency } from "../utils/format";
+import { getSharedMarketDataCoordinator, resolveEntryValue } from "../market-data/coordinator";
 import {
   computeDatedBeta,
   resolveDatedReturns,
@@ -26,6 +27,7 @@ import {
   normalizeBuiltinDisabledPluginIds,
   normalizeBuiltinPluginStateMap,
 } from "../plugins/ownership";
+import { isRecord } from "../utils/guards";
 
 /**
  * What a saved layout mirrors from the live session rather than from the
@@ -40,15 +42,11 @@ const SENSITIVE_KEY_PATTERN = /(token|secret|password|credential|private|api[_-]
 
 const log = debugLog.createLogger("sync");
 
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return value != null && typeof value === "object" && !Array.isArray(value);
-}
-
 function sanitizeUnknown(value: unknown): unknown {
   if (Array.isArray(value)) {
     return value.map(sanitizeUnknown).filter((entry) => entry !== undefined);
   }
-  if (!isPlainObject(value)) return value;
+  if (!isRecord(value)) return value;
 
   const output: Record<string, unknown> = {};
   for (const [key, child] of Object.entries(value)) {
@@ -418,16 +416,21 @@ function collectAnalyticsByPortfolio(
     }
     const portfolioReturns = unsupported ? [] : computeWeightedPortfolioReturns(datedReturnSeries);
     const previewAnalytics = getSyncedProfileAnalytics(portfolio.id);
+    // The broker's own returns do not depend on the holdings' price histories.
+    const accountBasis = previewAnalytics?.basis === "account";
+    // A weighted history of today's holdings is not the investor's actual
+    // one-year account return. Only preserve an explicitly supplied preview.
+    const oneYearReturn = invalidHistory && !accountBasis ? null : previewAnalytics?.oneYearReturn ?? null;
+    const spyBeta = (invalidHistory && !accountBasis) || spySample.integrity ? null : previewAnalytics?.spyBeta
+      ?? (
+        portfolioReturns.length > 0 && spyReturns.length > 0
+          ? computeDatedBeta(portfolioReturns, spyReturns)
+          : null
+      );
     output[portfolio.id] = {
-      // A weighted history of today's holdings is not the investor's actual
-      // one-year account return. Only preserve an explicitly supplied preview.
-      oneYearReturn: invalidHistory ? null : previewAnalytics?.oneYearReturn ?? null,
-      spyBeta: invalidHistory || spySample.integrity ? null : previewAnalytics?.spyBeta
-        ?? (
-          portfolioReturns.length > 0 && spyReturns.length > 0
-            ? computeDatedBeta(portfolioReturns, spyReturns)
-            : null
-        ),
+      oneYearReturn,
+      spyBeta,
+      basis: oneYearReturn == null && spyBeta == null ? null : previewAnalytics?.basis ?? "holdings",
     };
   }
   return output;
@@ -464,6 +467,39 @@ function isSyncableTicker(metadata: Pick<SanitizedTickerMetadata, "portfolios" |
     || metadata.positions.length > 0;
 }
 
+/**
+ * USD-per-unit rates for the base currency and every currency a holding is
+ * valued in, read from the same FX store the portfolio panes use. A currency
+ * without a usable rate stays missing, so its holdings count as unsupported.
+ */
+async function loadHoldingExchangeRates(
+  config: AppConfig,
+  tickers: Map<string, TickerRecord>,
+  financials: Map<string, TickerFinancials>,
+): Promise<Map<string, number>> {
+  const rates = new Map([["USD", 1]]);
+  const coordinator = getSharedMarketDataCoordinator();
+  if (!coordinator) return rates;
+  const currencies = new Set<string>();
+  const track = (currency: string | undefined) => {
+    const normalized = currency?.trim().toUpperCase();
+    if (normalized && normalized !== "USD") currencies.add(normalized);
+  };
+  track(config.baseCurrency);
+  for (const ticker of tickers.values()) {
+    if (ticker.metadata.positions.length === 0) continue;
+    track(financials.get(ticker.metadata.ticker)?.quote?.currency);
+    for (const position of ticker.metadata.positions) track(position.currency);
+  }
+  await Promise.all([...currencies].map(async (currency) => {
+    // A failed FX load must not hold back the rest of the push.
+    await coordinator.loadFxRate(currency).catch(() => {});
+    const rate = resolveEntryValue(coordinator.getFxEntry(currency));
+    if (rate != null) rates.set(currency, rate);
+  }));
+  return rates;
+}
+
 function collectCoreCollectionsPayload(
   config: AppConfig,
   tickers: Map<string, TickerRecord>,
@@ -475,17 +511,12 @@ function collectCoreCollectionsPayload(
     .map((ticker) => sanitizeTickerMetadata(ticker.metadata, financials.get(ticker.metadata.ticker)))
     .filter(isSyncableTicker);
 
+  // Only the USD anchor goes on the wire, as before: readers of the snapshot
+  // use any rate found here instead of fetching a current one, and a rate
+  // loaded for this push would age with it.
   return {
     baseCurrency: config.baseCurrency,
-    exchangeRates: Object.fromEntries(
-      [...exchangeRates.entries()]
-        .filter(([currency, rate]) => (
-          typeof currency === "string" &&
-          Number.isFinite(rate) &&
-          rate > 0
-        ))
-        .map(([currency, rate]) => [currency.trim().toUpperCase(), rate]),
-    ),
+    exchangeRates: { USD: 1 },
     portfolios: config.portfolios.map(sanitizePortfolio),
     watchlists: config.watchlists.map(sanitizeWatchlist),
     analyticsByPortfolio: collectAnalyticsByPortfolio(config, tickers, financials, exchangeRates, brokerAccounts),
@@ -495,12 +526,13 @@ function collectCoreCollectionsPayload(
 }
 
 function hydrateProfileAnalytics(payload: Record<string, unknown>): void {
-  if (!isPlainObject(payload.analyticsByPortfolio)) return;
+  if (!isRecord(payload.analyticsByPortfolio)) return;
   for (const [portfolioId, analytics] of Object.entries(payload.analyticsByPortfolio)) {
-    if (!isPlainObject(analytics)) continue;
+    if (!isRecord(analytics)) continue;
     setSyncedProfileAnalytics(portfolioId, {
       oneYearReturn: typeof analytics.oneYearReturn === "number" ? analytics.oneYearReturn : null,
       spyBeta: typeof analytics.spyBeta === "number" ? analytics.spyBeta : null,
+      basis: analytics.basis === "account" || analytics.basis === "holdings" ? analytics.basis : null,
     });
   }
 }
@@ -510,11 +542,11 @@ function valuesEqual(left: unknown, right: unknown): boolean {
 }
 
 function isPluginStateMap(value: unknown): value is Record<string, Record<string, unknown>> {
-  return isPlainObject(value) && Object.values(value).every(isPlainObject);
+  return isRecord(value) && Object.values(value).every(isRecord);
 }
 
 function withoutSessionLayoutState(savedLayout: SavedLayout): SavedLayout {
-  if (!isPlainObject(savedLayout)) return savedLayout;
+  if (!isRecord(savedLayout)) return savedLayout;
   if (!SESSION_SAVED_LAYOUT_KEYS.some((key) => key in savedLayout)) return savedLayout;
   const { paneState: _paneState, focusedPaneId: _focusedPaneId, activePanel: _activePanel, ...rest } = savedLayout;
   return rest;
@@ -531,7 +563,7 @@ function withLocalSessionLayoutState(
 ): SavedLayout[] {
   const localByName = new Map(local.map((savedLayout) => [savedLayout?.name, savedLayout]));
   return pulled.map((savedLayout, index) => {
-    if (!isPlainObject(savedLayout)) return savedLayout;
+    if (!isRecord(savedLayout)) return savedLayout;
     const stripped = withoutSessionLayoutState(savedLayout);
     const source = localByName.get(savedLayout.name) ?? local[index];
     if (!source) return stripped;
@@ -550,12 +582,12 @@ function mergeConfigPayload(
   baselineConfig: AppConfig = config,
   lastSyncedPayload?: unknown,
 ): AppConfig | null {
-  if (!isPlainObject(payload)) return null;
+  if (!isRecord(payload)) return null;
   const next: AppConfig = { ...config };
   // Two guards, both needed. baselineConfig catches edits made while this pull
   // was in flight; lastSyncedPayload catches edits made while the app was not
   // running at all (CLI writes, offline edits), which otherwise look pristine.
-  const lastSynced = isPlainObject(lastSyncedPayload) ? lastSyncedPayload : null;
+  const lastSynced = isRecord(lastSyncedPayload) ? lastSyncedPayload : null;
   const localPayload = lastSynced
     ? collectCoreConfigPayload(config) as Record<string, unknown>
     : null;
@@ -641,10 +673,10 @@ function mergeConfigPayload(
 }
 
 function lastSyncedTickersById(baselinePayload: unknown): Map<string, Record<string, unknown>> | null {
-  if (!isPlainObject(baselinePayload) || !Array.isArray(baselinePayload.tickers)) return null;
+  if (!isRecord(baselinePayload) || !Array.isArray(baselinePayload.tickers)) return null;
   const byId = new Map<string, Record<string, unknown>>();
   for (const entry of baselinePayload.tickers) {
-    if (isPlainObject(entry) && typeof entry.ticker === "string") byId.set(entry.ticker, entry);
+    if (isRecord(entry) && typeof entry.ticker === "string") byId.set(entry.ticker, entry);
   }
   return byId;
 }
@@ -692,22 +724,22 @@ export const coreConfigSyncContributor: SyncContributor = {
 export const coreCollectionsSyncContributor: SyncContributor = {
   id: "core.collections",
   schemaVersion: 1,
-  collect: ({ state }) => collectCoreCollectionsPayload(
+  collect: async ({ state }) => collectCoreCollectionsPayload(
     state.config,
     state.tickers,
     state.financials,
-    state.exchangeRates,
+    await loadHoldingExchangeRates(state.config, state.tickers, state.financials),
     state.brokerAccounts,
   ),
   apply: async (payload, { baselinePayload, getState, isCurrent, dispatch, tickerRepository }) => {
-    if (!isPlainObject(payload)) return;
+    if (!isRecord(payload)) return;
     hydrateProfileAnalytics(payload);
     const lastSyncedTickers = lastSyncedTickersById(baselinePayload);
     const incomingRecords: TickerRecord[] = [];
     const rawTickers = Array.isArray(payload.tickers) ? payload.tickers : [];
     for (const rawTicker of rawTickers) {
       if (!isCurrent()) return;
-      if (!isPlainObject(rawTicker)) continue;
+      if (!isRecord(rawTicker)) continue;
       const current = typeof rawTicker.ticker === "string"
         ? getState().tickers.get(rawTicker.ticker)
         : null;

package/src/sync/profile-analytics.ts

@@ -8,15 +8,18 @@ function finiteMetric(value: number | null | undefined): number | null {
 
 function normalizeAnalytics(analytics: PublicPortfolioAnalytics | null | undefined): PublicPortfolioAnalytics | null {
   if (!analytics) return null;
-  const normalized = {
+  const normalized: PublicPortfolioAnalytics = {
     oneYearReturn: finiteMetric(analytics.oneYearReturn),
     spyBeta: finiteMetric(analytics.spyBeta),
+    basis: analytics.basis === "account" || analytics.basis === "holdings" ? analytics.basis : null,
   };
   return normalized.oneYearReturn != null || normalized.spyBeta != null ? normalized : null;
 }
 
 function sameAnalytics(left: PublicPortfolioAnalytics | null, right: PublicPortfolioAnalytics | null): boolean {
-  return left?.oneYearReturn === right?.oneYearReturn && left?.spyBeta === right?.spyBeta;
+  return left?.oneYearReturn === right?.oneYearReturn
+    && left?.spyBeta === right?.spyBeta
+    && (left?.basis ?? null) === (right?.basis ?? null);
 }
 
 export function setSyncedProfileAnalytics(

package/src/telemetry/crash-reports-dom.ts

@@ -0,0 +1,74 @@
+import type { StorageLike } from "../data/json-storage";
+import { flushCrashReports, reportCrash } from "./crash-reports";
+
+/** The desktop view and the web terminal: window-level errors and the browser's install id. */
+
+const INSTALL_ID_STORAGE_KEY = "gloomberb.web.install-id";
+const INSTALL_ID = /^[a-f0-9-]{36}$/;
+
+/** A random id kept in local storage, created on first use; crash reports and usage counts carry it, nothing else. */
+export function readOrCreateBrowserInstallId(storage: StorageLike | undefined = readLocalStorage()): string | null {
+  try {
+    const stored = storage?.getItem(INSTALL_ID_STORAGE_KEY);
+    if (stored && INSTALL_ID.test(stored)) return stored;
+    const created = crypto.randomUUID();
+    storage?.setItem(INSTALL_ID_STORAGE_KEY, created);
+    return created;
+  } catch {
+    // Private browsing may refuse storage; a per-load id still identifies the report.
+    return crypto.randomUUID();
+  }
+}
+
+function readLocalStorage(): StorageLike | undefined {
+  try {
+    return typeof localStorage === "undefined" ? undefined : localStorage;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The browser's own opt-out signals, the web equivalent of `DO_NOT_TRACK=1`. */
+export function browserDoNotTrack(): boolean {
+  try {
+    const nav = navigator as Navigator & { globalPrivacyControl?: boolean };
+    return nav.doNotTrack === "1" || nav.globalPrivacyControl === true;
+  } catch {
+    return false;
+  }
+}
+
+/** The user agent's platform, the closest a browser context has to an OS name. */
+export function describeBrowserOs(): string {
+  try {
+    const data = (navigator as Navigator & { userAgentData?: { platform?: string } }).userAgentData;
+    return data?.platform || navigator.platform || "";
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Reports what escapes React: errors thrown outside a render, and promise
+ * rejections nobody handled. A page going away flushes what is queued; the
+ * request uses `keepalive`, so the browser finishes it after unload.
+ */
+export function installWindowCrashListeners(target: Window = window): () => void {
+  const onError = (event: ErrorEvent) => {
+    reportCrash(event.error ?? event.message, { kind: "uncaught" });
+  };
+  const onRejection = (event: PromiseRejectionEvent) => {
+    reportCrash(event.reason, { kind: "unhandled-rejection" });
+  };
+  const onPageHide = () => {
+    void flushCrashReports({ timeoutMs: 1_000 });
+  };
+  target.addEventListener("error", onError);
+  target.addEventListener("unhandledrejection", onRejection);
+  target.addEventListener("pagehide", onPageHide);
+  return () => {
+    target.removeEventListener("error", onError);
+    target.removeEventListener("unhandledrejection", onRejection);
+    target.removeEventListener("pagehide", onPageHide);
+  };
+}

package/src/telemetry/crash-reports-node.ts

@@ -0,0 +1,170 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { homedir, release } from "os";
+import { join } from "path";
+import type { CrashReportSurface } from "../api-client";
+import type { TelemetryConfig } from "../types/config";
+import {
+  crashReportsEnabled,
+  flushCrashReports,
+  reportCrash,
+  spoolPendingCrashReports,
+  type CrashReporterHost,
+  type SpooledCrashReport,
+} from "./crash-reports";
+
+/**
+ * The crash reporter for a Bun process: the terminal app and the desktop
+ * app's main process. Reads the off switch from the config and the
+ * environment, keeps the install id in a file next to config.json, and
+ * spools a batch to disk when the process is about to die.
+ */
+
+const INSTALL_ID_FILE = "install-id";
+const SPOOL_FILE = "crash-reports.json";
+const MAX_SPOOLED_REPORTS = 5;
+const INSTALL_ID = /^[a-f0-9-]{36}$/;
+/** How long an exit path waits for a report before leaving anyway. */
+export const CRASH_REPORT_EXIT_FLUSH_MS = 1_500;
+
+const installIds = new Map<string, string>();
+
+/** Platform, kernel release and architecture, such as `darwin 24.5.0 arm64`. */
+export function describeNodeOs(): string {
+  let osRelease = "";
+  try {
+    osRelease = release();
+  } catch {
+    /* Unavailable on some runtimes; the platform alone still helps. */
+  }
+  return [process.platform, osRelease, process.arch].filter(Boolean).join(" ");
+}
+
+/**
+ * The random id that identifies this install in crash reports and usage
+ * counts, created on first use and kept in `<dataDir>/install-id`. It is used
+ * for nothing else.
+ */
+export function readOrCreateInstallId(dataDir: string): string | null {
+  const cached = installIds.get(dataDir);
+  if (cached) return cached;
+  const path = join(dataDir, INSTALL_ID_FILE);
+  try {
+    const existing = readFileSync(path, "utf-8").trim();
+    if (INSTALL_ID.test(existing)) {
+      installIds.set(dataDir, existing);
+      return existing;
+    }
+  } catch {
+    /* First run, or unreadable: create one below. */
+  }
+  try {
+    const created = crypto.randomUUID();
+    mkdirSync(dataDir, { recursive: true });
+    writeFileSync(path, `${created}\n`, "utf-8");
+    installIds.set(dataDir, created);
+    return created;
+  } catch {
+    return null;
+  }
+}
+
+function spoolPath(dataDir: string): string {
+  return join(dataDir, SPOOL_FILE);
+}
+
+function readSpool(dataDir: string): SpooledCrashReport[] {
+  try {
+    const path = spoolPath(dataDir);
+    if (!existsSync(path)) return [];
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf-8"));
+    return Array.isArray(parsed) ? (parsed as SpooledCrashReport[]).slice(0, MAX_SPOOLED_REPORTS) : [];
+  } catch {
+    return [];
+  }
+}
+
+export interface NodeCrashReporterHostOptions {
+  surface: CrashReportSurface;
+  /** The current config, or null before it is loaded. */
+  getConfig(): { dataDir: string; telemetry?: TelemetryConfig } | null;
+  env?: Record<string, string | undefined>;
+}
+
+export function createNodeCrashReporterHost(options: NodeCrashReporterHostOptions): CrashReporterHost {
+  const env = options.env ?? process.env;
+  const dataDir = () => options.getConfig()?.dataDir ?? null;
+  return {
+    surface: options.surface,
+    os: describeNodeOs(),
+    homeDir: homedir(),
+    isEnabled: () => crashReportsEnabled(options.getConfig(), env),
+    getInstallId: () => {
+      const dir = dataDir();
+      return dir ? readOrCreateInstallId(dir) : null;
+    },
+    spool: (report) => {
+      const dir = dataDir();
+      if (!dir) return;
+      const reports = [...readSpool(dir), report].slice(-MAX_SPOOLED_REPORTS);
+      writeFileSync(spoolPath(dir), JSON.stringify(reports), "utf-8");
+    },
+    clearSpool: () => {
+      const dir = dataDir();
+      if (dir) rmSync(spoolPath(dir), { force: true });
+    },
+    takeSpooled: async () => {
+      const dir = dataDir();
+      if (!dir) return [];
+      const reports = readSpool(dir);
+      rmSync(spoolPath(dir), { force: true });
+      return reports;
+    },
+  };
+}
+
+
+/**
+ * A read from a terminal that has gone away (its window closed, its tmux pane
+ * killed) fails with EIO just before the hangup signal ends the process. That
+ * is the user leaving, not a crash.
+ */
+export function isTerminalHangup(error: unknown): boolean {
+  const { code, syscall } = (error ?? {}) as { code?: unknown; syscall?: unknown };
+  return code === "EIO" && syscall === "read";
+}
+
+function exitAfterFlush(error: unknown): void {
+  // The default for a process with no listener: print the error and exit 1.
+  console.error(error);
+  void flushCrashReports({ timeoutMs: CRASH_REPORT_EXIT_FLUSH_MS }).finally(() => process.exit(1));
+}
+
+/**
+ * Reports uncaught exceptions and unhandled rejections.
+ *
+ * Whether the process survives is decided by whoever else listens: the
+ * terminal renderer logs and carries on, and Electrobun stops the desktop
+ * process. This listener only reports, and it goes first so a listener that
+ * exits synchronously (Electrobun's does) still leaves a spooled batch on
+ * disk for the next launch. When it is the only listener, it keeps the
+ * runtime's default of exiting with status 1, after a bounded flush.
+ */
+export function installProcessCrashListeners(): () => void {
+  const onUncaughtException = (error: unknown) => {
+    if (!isTerminalHangup(error)) {
+      reportCrash(error, { kind: "uncaught" });
+      spoolPendingCrashReports();
+    }
+    if (process.listenerCount("uncaughtException") <= 1) exitAfterFlush(error);
+  };
+  const onUnhandledRejection = (reason: unknown) => {
+    reportCrash(reason, { kind: "unhandled-rejection" });
+    if (process.listenerCount("unhandledRejection") <= 1) exitAfterFlush(reason);
+  };
+  process.prependListener("uncaughtException", onUncaughtException);
+  process.prependListener("unhandledRejection", onUnhandledRejection);
+  return () => {
+    process.removeListener("uncaughtException", onUncaughtException);
+    process.removeListener("unhandledRejection", onUnhandledRejection);
+  };
+}