ubume 0.1.0

package/src/core/models/codexModelsCacheSeed.ts

@@ -0,0 +1,153 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { formatReasoningLabel } from "../../config/settings.js";
+import type { ProviderModel } from "../providerRuntime/types.js";
+import type {
+  CodexModelCapabilities,
+  CodexModelCapability,
+  ReasoningEffortCapability,
+} from "./codexModelCapabilities.js";
+import { loadCachedProviderModels, type CachedProviderModels } from "./providerModelCache.js";
+
+// The codex CLI maintains its own model catalog cache with slugs, labels and
+// reasoning levels. Reading it seeds Ubume's OpenAI model list instantly —
+// no subprocess — and stays current because the codex CLI refreshes the file
+// on its own runs.
+// Resolved per call from env (matching claudeCodeDiscovery) so HOME
+// redirection in tests holds — Bun's homedir() ignores runtime HOME changes.
+export function getCodexModelsCacheFile(): string {
+  const home = process.env.USERPROFILE ?? process.env.HOME ?? homedir();
+  return join(home, ".codex", "models_cache.json");
+}
+
+interface CodexSeed {
+  fetchedAt: number;
+  models: readonly ProviderModel[];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function asString(value: unknown): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function parseReasoningLevels(raw: unknown): readonly ReasoningEffortCapability[] | null {
+  if (!Array.isArray(raw)) {
+    return null;
+  }
+  const levels = raw
+    .map((entry): ReasoningEffortCapability | null => {
+      if (!isRecord(entry)) {
+        return null;
+      }
+      const id = asString(entry.effort);
+      if (!id) {
+        return null;
+      }
+      return { id, label: formatReasoningLabel(id), description: asString(entry.description) };
+    })
+    .filter((entry): entry is ReasoningEffortCapability => entry !== null);
+  return levels.length > 0 ? levels : null;
+}
+
+function parseSeedModel(raw: unknown): ProviderModel | null {
+  if (!isRecord(raw)) {
+    return null;
+  }
+  // Models with visibility "hide" are internal codex routes (e.g. auto-review).
+  if (asString(raw.visibility) === "hide") {
+    return null;
+  }
+  const modelId = asString(raw.slug);
+  if (!modelId) {
+    return null;
+  }
+  return {
+    id: modelId,
+    modelId,
+    label: asString(raw.display_name) ?? modelId,
+    description: asString(raw.description),
+    defaultReasoningLevel: asString(raw.default_reasoning_level),
+    supportedReasoningLevels: parseReasoningLevels(raw.supported_reasoning_levels),
+    source: "discovered",
+  };
+}
+
+export function loadCodexSeedModels(cacheFile = getCodexModelsCacheFile()): CodexSeed | null {
+  try {
+    if (!existsSync(cacheFile)) {
+      return null;
+    }
+    const parsed: unknown = JSON.parse(readFileSync(cacheFile, "utf8"));
+    if (!isRecord(parsed) || !Array.isArray(parsed.models)) {
+      return null;
+    }
+    const models = parsed.models
+      .map(parseSeedModel)
+      .filter((model): model is ProviderModel => model !== null);
+    if (models.length === 0) {
+      return null;
+    }
+    const fetchedAtRaw = asString(parsed.fetched_at);
+    const fetchedAt = fetchedAtRaw ? Date.parse(fetchedAtRaw) : Number.NaN;
+    return { fetchedAt: Number.isFinite(fetchedAt) ? fetchedAt : 0, models };
+  } catch {
+    return null;
+  }
+}
+
+// Freshest locally known OpenAI models without spawning a subprocess:
+// codex's own cache file vs Ubume's persisted last-good discovery.
+export function loadSeededOpenAiModels(options: {
+  codexCacheFile?: string;
+  providerCacheFile?: string;
+} = {}): CachedProviderModels | null {
+  const seed = loadCodexSeedModels(options.codexCacheFile);
+  const persisted = options.providerCacheFile === undefined
+    ? loadCachedProviderModels("openai")
+    : loadCachedProviderModels("openai", options.providerCacheFile);
+  if (seed && (!persisted || seed.fetchedAt >= persisted.discoveredAt)) {
+    return { discoveredAt: seed.fetchedAt, models: seed.models };
+  }
+  return persisted;
+}
+
+function toCapability(model: ProviderModel, index: number): CodexModelCapability {
+  return {
+    id: model.id,
+    model: model.modelId,
+    label: model.label,
+    description: model.description,
+    available: true,
+    hidden: false,
+    isDefault: index === 0,
+    defaultReasoningLevel: model.defaultReasoningLevel,
+    supportedReasoningLevels: model.supportedReasoningLevels,
+    reasoningLevelCount: model.supportedReasoningLevels ? model.supportedReasoningLevels.length : null,
+    source: "runtime",
+    raw: model,
+  };
+}
+
+// Capabilities for the OpenAI picker sourced purely from local caches.
+// Returns null when nothing is cached yet (first ever launch).
+export function loadSeededCodexCapabilities(options: {
+  codexCacheFile?: string;
+  providerCacheFile?: string;
+} = {}): CodexModelCapabilities | null {
+  const seeded = loadSeededOpenAiModels(options);
+  if (!seeded) {
+    return null;
+  }
+  return {
+    status: "ready",
+    source: "runtime",
+    models: seeded.models.map(toCapability),
+    discoveredAt: seeded.discoveredAt,
+    executable: null,
+    error: null,
+  };
+}

package/src/core/models/modelSpecs.ts

@@ -0,0 +1,303 @@
+import { existsSync, readFileSync, renameSync, writeFileSync } from "fs";
+import { MODEL_SPECS_FILE, LEGACY_MODEL_SPECS_FILE } from "../../config/settings.js";
+
+export type ModelSpecStatus = "verified" | "loading" | "unknown";
+
+export interface VerifiedModelSpec {
+  status: "verified";
+  contextWindow: number;
+  maxOutputTokens: number;
+  sourceUrl: string;
+  verifiedAt: number;
+  isEstimated?: boolean;
+}
+
+export interface PendingModelSpec {
+  status: "loading" | "unknown";
+  contextWindow: null;
+  maxOutputTokens: null;
+  sourceUrl: string;
+  verifiedAt: null;
+  error: string | null;
+}
+
+export type ModelSpec = VerifiedModelSpec | PendingModelSpec;
+
+export const MODEL_SPEC_DOC_URLS: Record<string, string> = {
+  "gpt-5.4": "https://developers.openai.com/api/docs/models/gpt-5.4",
+  "gpt-5.4-mini": "https://developers.openai.com/api/docs/models/gpt-5.4-mini",
+  "gpt-5.3-codex": "https://developers.openai.com/api/docs/models/gpt-5.3-codex",
+  "gpt-5.2": "https://developers.openai.com/api/docs/models/gpt-5.2",
+};
+
+// Legacy model spec registry. Context-window display now goes through
+// providerRuntime/contextMetadata.ts so values are source-aware and provider
+// scoped. Keep this empty to avoid showing broad or guessed model limits.
+export interface KnownModelSpec {
+  contextWindow: number;
+  maxOutputTokens: number;
+}
+
+export const KNOWN_MODEL_SPECS: Record<string, KnownModelSpec> = {};
+
+type ModelSpecCache = Partial<Record<string, VerifiedModelSpec>>;
+
+interface ModelSpecServiceOptions {
+  cacheFile?: string;
+  fetchImpl?: typeof fetch;
+  now?: () => number;
+}
+
+function createPendingModelSpec(
+  model: string,
+  status: PendingModelSpec["status"],
+  error: string | null = null,
+): PendingModelSpec {
+  return {
+    status,
+    contextWindow: null,
+    maxOutputTokens: null,
+    sourceUrl: getModelSpecDocUrl(model),
+    verifiedAt: null,
+    error,
+  };
+}
+
+function getModelSpecDocUrl(model: string): string {
+  return MODEL_SPEC_DOC_URLS[model] ?? `https://developers.openai.com/api/docs/models/${encodeURIComponent(model)}`;
+}
+
+export function createLoadingModelSpec(model: string): ModelSpec {
+  return createPendingModelSpec(model, "loading");
+}
+
+export function createUnknownModelSpec(model: string, error: string | null = null): ModelSpec {
+  return createPendingModelSpec(model, "unknown", error);
+}
+
+export function parseTokenCount(rawValue: string): number | null {
+  const normalized = rawValue.trim().replace(/\s+/g, "").toLowerCase();
+  if (!normalized) return null;
+
+  const suffix = normalized.endsWith("m")
+    ? 1_000_000
+    : normalized.endsWith("k")
+      ? 1_000
+      : 1;
+  const numericText = suffix === 1 ? normalized : normalized.slice(0, -1);
+  const numeric = Number.parseFloat(numericText.replace(/,/g, ""));
+  if (!Number.isFinite(numeric)) return null;
+
+  return Math.round(numeric * suffix);
+}
+
+export function stripHtmlToText(html: string): string {
+  return html
+    .replace(/<script\b[\s\S]*?<\/script[^>]*>/gi, " ")
+    .replace(/<style[\s\S]*?<\/style>/gi, " ")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&nbsp;|&#160;/gi, " ")
+    .replace(/&quot;/gi, "\"")
+    .replace(/&#39;|&apos;/gi, "'")
+    .replace(/&amp;/gi, "&")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+export function extractModelSpecFromDocText(
+  model: string,
+  text: string,
+  verifiedAt = Date.now(),
+): VerifiedModelSpec | null {
+  const normalized = text.replace(/\u00a0/g, " ").replace(/\s+/g, " ");
+  const contextMatch = normalized.match(/(\d[\d,.]*(?:\s*[mk])?)\s+context\s+window/i);
+  const maxOutputMatch = normalized.match(/(\d[\d,.]*(?:\s*[mk])?)\s+max\s+output\s+tokens/i);
+
+  const contextWindow = contextMatch ? parseTokenCount(contextMatch[1] ?? "") : null;
+  const maxOutputTokens = maxOutputMatch ? parseTokenCount(maxOutputMatch[1] ?? "") : null;
+  if (!contextWindow || !maxOutputTokens) {
+    return null;
+  }
+
+  return {
+    status: "verified",
+    contextWindow,
+    maxOutputTokens,
+    sourceUrl: getModelSpecDocUrl(model),
+    verifiedAt,
+  };
+}
+
+function isVerifiedModelSpec(value: unknown): value is VerifiedModelSpec {
+  if (!value || typeof value !== "object") return false;
+
+  const candidate = value as Partial<VerifiedModelSpec>;
+  return candidate.status === "verified"
+    && typeof candidate.contextWindow === "number"
+    && Number.isFinite(candidate.contextWindow)
+    && typeof candidate.maxOutputTokens === "number"
+    && Number.isFinite(candidate.maxOutputTokens)
+    && typeof candidate.sourceUrl === "string"
+    && typeof candidate.verifiedAt === "number"
+    && Number.isFinite(candidate.verifiedAt);
+}
+
+export function loadModelSpecCache(cacheFile = MODEL_SPECS_FILE): ModelSpecCache {
+  if (cacheFile === MODEL_SPECS_FILE && !existsSync(MODEL_SPECS_FILE) && existsSync(LEGACY_MODEL_SPECS_FILE)) {
+    cacheFile = LEGACY_MODEL_SPECS_FILE;
+  }
+  try {
+    const raw = JSON.parse(readFileSync(cacheFile, "utf-8")) as Record<string, unknown>;
+    const cache: ModelSpecCache = {};
+
+    for (const [model, value] of Object.entries(raw)) {
+      if (isVerifiedModelSpec(value)) {
+        cache[model] = value;
+      }
+    }
+
+    return cache;
+  } catch {
+    return {};
+  }
+}
+
+export function saveModelSpecCache(cache: ModelSpecCache, cacheFile = MODEL_SPECS_FILE): void {
+  try {
+    const tmpFile = `${cacheFile}.tmp`;
+    writeFileSync(tmpFile, JSON.stringify(cache, null, 2), "utf-8");
+    renameSync(tmpFile, cacheFile);
+  } catch {
+    // Best-effort cache only.
+  }
+}
+
+export async function fetchModelSpecFromDocs(
+  model: string,
+  fetchImpl: typeof fetch = fetch,
+  verifiedAt = Date.now(),
+): Promise<VerifiedModelSpec> {
+  const response = await fetchImpl(getModelSpecDocUrl(model), {
+    headers: {
+      Accept: "text/html,application/xhtml+xml",
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error(`Spec request failed with ${response.status}`);
+  }
+
+  const html = await response.text();
+  const parsed = extractModelSpecFromDocText(model, stripHtmlToText(html), verifiedAt);
+  if (!parsed) {
+    throw new Error(`Unable to parse model spec for ${model}`);
+  }
+
+  return parsed;
+}
+
+export interface ResolveModelSpecOptions {
+  // Persisted verified cache (loaded synchronously at startup).
+  cache?: Partial<Record<string, VerifiedModelSpec>>;
+  // Runtime discovery contextWindow if/when Codex starts providing it.
+  runtimeContextWindow?: number | null;
+  runtimeMaxOutputTokens?: number | null;
+  // Set true when a background refresh is in progress and no other source
+  // has produced verified numbers — lets callers render a "loading" state
+  // instead of "unknown".
+  refreshInFlight?: boolean;
+  now?: () => number;
+}
+
+// Single authoritative resolver. Precedence:
+//   1. Runtime discovery metadata (if contextWindow is provided)
+//   2. Persistent spec cache (~/.ubume-model-specs.json)
+//   3. Trusted static registry (KNOWN_MODEL_SPECS)
+//   4. Loading (if a background refresh is in-flight)
+//   5. Unknown
+export function resolveModelSpec(model: string, options: ResolveModelSpecOptions = {}): ModelSpec {
+  const now = options.now?.() ?? Date.now();
+
+  const runtimeCtx = options.runtimeContextWindow;
+  const runtimeMax = options.runtimeMaxOutputTokens;
+  if (
+    typeof runtimeCtx === "number" && Number.isFinite(runtimeCtx) && runtimeCtx > 0
+    && typeof runtimeMax === "number" && Number.isFinite(runtimeMax) && runtimeMax > 0
+  ) {
+    return {
+      status: "verified",
+      contextWindow: runtimeCtx,
+      maxOutputTokens: runtimeMax,
+      sourceUrl: getModelSpecDocUrl(model),
+      verifiedAt: now,
+    };
+  }
+
+  const cached = options.cache?.[model];
+  if (cached && cached.status === "verified") {
+    return cached;
+  }
+
+  const known = KNOWN_MODEL_SPECS[model];
+  if (known) {
+    return {
+      status: "verified",
+      contextWindow: known.contextWindow,
+      maxOutputTokens: known.maxOutputTokens,
+      sourceUrl: getModelSpecDocUrl(model),
+      verifiedAt: now,
+    };
+  }
+
+  if (options.refreshInFlight) {
+    return createLoadingModelSpec(model);
+  }
+
+  return createUnknownModelSpec(model);
+}
+
+export function areModelSpecsEqual(left: ModelSpec | undefined, right: ModelSpec): boolean {
+  if (!left) return false;
+  if (left.status !== right.status) return false;
+
+  return left.contextWindow === right.contextWindow
+    && left.maxOutputTokens === right.maxOutputTokens
+    && left.sourceUrl === right.sourceUrl
+    && left.verifiedAt === right.verifiedAt
+    && ("error" in left ? left.error : null) === ("error" in right ? right.error : null);
+}
+
+export function createModelSpecService(options: ModelSpecServiceOptions = {}) {
+  const cacheFile = options.cacheFile ?? MODEL_SPECS_FILE;
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const now = options.now ?? Date.now;
+  // Persisted specs are kept for saving, not for live UI trust.
+  const cache = loadModelSpecCache(cacheFile);
+  const inflight = new Map<string, Promise<ModelSpec>>();
+
+  return {
+    async refreshSpec(model: string): Promise<ModelSpec> {
+      const current = inflight.get(model);
+      if (current) return current;
+
+      const refreshPromise = (async () => {
+        try {
+          const verified = await fetchModelSpecFromDocs(model, fetchImpl, now());
+          cache[model] = verified;
+          saveModelSpecCache(cache, cacheFile);
+          return verified;
+        } catch (error) {
+          return createUnknownModelSpec(
+            model,
+            error instanceof Error ? error.message : "Unknown model spec failure",
+          );
+        } finally {
+          inflight.delete(model);
+        }
+      })();
+
+      inflight.set(model, refreshPromise);
+      return refreshPromise;
+    },
+  };
+}

package/src/core/models/providerModelCache.ts

@@ -0,0 +1,94 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { ProviderId } from "../providerLauncher/types.js";
+import type { ProviderModel } from "../providerRuntime/types.js";
+
+// Persistent last-good model discovery results, one entry per provider.
+// Lets pickers open instantly with the previous session's discovered models
+// while a background refresh runs. Corrupt or missing cache degrades to null.
+// Resolved per call from env (matching claudeCodeDiscovery) so HOME
+// redirection in tests holds — Bun's homedir() ignores runtime HOME changes.
+export function getProviderModelCacheFile(): string {
+  const home = process.env.USERPROFILE ?? process.env.HOME ?? homedir();
+  const ubumePath = join(home, ".ubume-model-cache.json");
+  if (existsSync(ubumePath)) return ubumePath;
+  const legacyPath = join(home, ".codexa-model-cache.json");
+  if (existsSync(legacyPath)) return legacyPath;
+  return ubumePath;
+}
+
+const CACHE_VERSION = 1;
+
+export interface CachedProviderModels {
+  discoveredAt: number;
+  models: readonly ProviderModel[];
+}
+
+interface ProviderModelCacheFile {
+  version: number;
+  providers: Partial<Record<ProviderId, CachedProviderModels>>;
+}
+
+function readCacheFile(cacheFile: string): ProviderModelCacheFile | null {
+  try {
+    if (!existsSync(cacheFile)) {
+      return null;
+    }
+    const parsed: unknown = JSON.parse(readFileSync(cacheFile, "utf8"));
+    if (
+      typeof parsed !== "object" || parsed === null || Array.isArray(parsed)
+      || (parsed as ProviderModelCacheFile).version !== CACHE_VERSION
+      || typeof (parsed as ProviderModelCacheFile).providers !== "object"
+      || (parsed as ProviderModelCacheFile).providers === null
+    ) {
+      return null;
+    }
+    return parsed as ProviderModelCacheFile;
+  } catch {
+    return null;
+  }
+}
+
+function isValidEntry(entry: unknown): entry is CachedProviderModels {
+  if (typeof entry !== "object" || entry === null) {
+    return false;
+  }
+  const candidate = entry as CachedProviderModels;
+  return typeof candidate.discoveredAt === "number"
+    && Array.isArray(candidate.models)
+    && candidate.models.every((model) =>
+      typeof model === "object" && model !== null
+      && typeof model.id === "string"
+      && typeof model.modelId === "string"
+      && typeof model.label === "string");
+}
+
+export function loadCachedProviderModels(
+  providerId: ProviderId,
+  cacheFile = getProviderModelCacheFile(),
+): CachedProviderModels | null {
+  const cache = readCacheFile(cacheFile);
+  const entry = cache?.providers?.[providerId];
+  if (!entry || !isValidEntry(entry) || entry.models.length === 0) {
+    return null;
+  }
+  return entry;
+}
+
+export function saveCachedProviderModels(
+  providerId: ProviderId,
+  entry: CachedProviderModels,
+  cacheFile = getProviderModelCacheFile(),
+): void {
+  if (entry.models.length === 0) {
+    return;
+  }
+  try {
+    const cache = readCacheFile(cacheFile) ?? { version: CACHE_VERSION, providers: {} };
+    cache.providers[providerId] = entry;
+    writeFileSync(cacheFile, `${JSON.stringify(cache, null, 2)}\n`, "utf8");
+  } catch {
+    // Persistence is best-effort; discovery still works without it.
+  }
+}

package/src/core/perf/profiler.ts

@@ -0,0 +1,125 @@
+import { appendFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+export interface PerfSession {
+  runId: string;
+  marks: Record<string, number>;
+  counters: Record<string, number>;
+  accumulations: Record<string, number>;
+  metadata: Record<string, unknown>;
+}
+
+let _enabled: boolean | null = null;
+let _session: PerfSession | null = null;
+
+export function isEnabled(): boolean {
+  if (_enabled === null) {
+    _enabled = process.env["UBUME_PERF"] === "1";
+  }
+  return _enabled;
+}
+
+export function startSession(runId: string): void {
+  if (!isEnabled()) return;
+  _session = { runId, marks: {}, counters: {}, accumulations: {}, metadata: {} };
+}
+
+export function mark(label: string): void {
+  if (_session) _session.marks[label] = performance.now();
+}
+
+export function inc(counter: string, by = 1): void {
+  if (_session) _session.counters[counter] = (_session.counters[counter] ?? 0) + by;
+}
+
+export function accumulate(key: string, ms: number): void {
+  if (_session) _session.accumulations[key] = (_session.accumulations[key] ?? 0) + ms;
+}
+
+export function setMeta(key: string, value: unknown): void {
+  if (_session) _session.metadata[key] = value;
+}
+
+export function getSession(): PerfSession | null {
+  return _session;
+}
+
+// ─── Formatting ───────────────────────────────────────────────────────────────
+
+function dur(session: PerfSession, from: string, to: string): string {
+  const a = session.marks[from];
+  const b = session.marks[to];
+  if (a === undefined || b === undefined) return "   ?";
+  return String(Math.round(b - a)).padStart(4);
+}
+
+const STAGE_ROWS: Array<[from: string, to: string, label: string, note?: string]> = [
+  ["submit", "dispatch_start", "submit → dispatch_start", "pre-dispatch overhead"],
+  ["dispatch_start", "provider_run_start", "dispatch_start → provider_run_start", "orchestration setup"],
+  ["exec_resolve_start", "exec_resolve_end", "exec_resolve", "cached after first run"],
+  ["caps_probe_start", "caps_probe_end", "caps_probe", "cached after first run"],
+  ["provider_run_start", "spawn_done", "provider_run_start → spawn_done", "spawn overhead"],
+  ["spawn_done", "first_chunk", "spawn_done → first_chunk  (TTFT)", "← backend latency"],
+  ["first_chunk", "first_render", "first_chunk → first_render", "render dispatch"],
+  ["first_chunk", "last_chunk", "streaming duration", "total stream time"],
+  ["last_chunk", "response_cb_start", "last_chunk → response_cb", ""],
+  ["snapshot_start", "snapshot_end", "workspace_snapshot  (blocking)", "← post-run overhead"],
+  ["finalize_start", "finalize_done", "finalize_start → finalize_done", ""],
+];
+
+export function buildSummary(session: PerfSession): string {
+  const lines: string[] = [
+    "┌── UBUME PERF REPORT ─────────────────────────────────────────",
+    "│ Stage                                         ms",
+  ];
+
+  const durations: Array<{ label: string; ms: number }> = [];
+
+  for (const [from, to, label, note] of STAGE_ROWS) {
+    const a = session.marks[from];
+    const b = session.marks[to];
+    const ms = a !== undefined && b !== undefined ? Math.round(b - a) : null;
+    const msStr = ms !== null ? String(ms).padStart(4) : "   ?";
+    const noteStr = note ? `  ${note}` : "";
+    lines.push(`│  ${label.padEnd(44)} ${msStr}ms${noteStr}`);
+    if (ms !== null) durations.push({ label, ms });
+  }
+
+  const c = session.counters;
+  const a = session.accumulations;
+  lines.push("│");
+  lines.push(
+    `│  Counters   chunks=${c["chunks"] ?? 0}  flushes=${c["flushes"] ?? 0}  progress_updates=${c["progress_updates"] ?? 0}`,
+  );
+  lines.push(`│  Sanitise   accumulated ${Math.round(a["sanitize_ms"] ?? 0)}ms across ${c["chunks"] ?? 0} chunks`);
+
+  const metaEntries = Object.entries(session.metadata);
+  if (metaEntries.length > 0) {
+    lines.push("│");
+    for (const [k, v] of metaEntries) {
+      lines.push(`│  ${k}: ${String(v)}`);
+    }
+  }
+
+  // Bottleneck: largest duration stage
+  if (durations.length > 0) {
+    const top = durations.reduce((a, b) => (b.ms > a.ms ? b : a));
+    lines.push("│");
+    lines.push(`│  ► BOTTLENECK: ${top.label} = ${top.ms}ms`);
+  }
+
+  lines.push("└───────────────────────────────────────────────────────────────");
+  return lines.join("\n");
+}
+
+// Sessions are appended as JSONL to ~/.ubume-perf.jsonl for offline analysis.
+export function persistSession(session: PerfSession): void {
+  try {
+    const logPath = join(homedir(), ".ubume-perf.jsonl");
+    const line = JSON.stringify({ ...session, ts: Date.now() }) + "\n";
+    appendFileSync(logPath, line, "utf8");
+  } catch {
+    // Profiling must never crash the app.
+  }
+}