routstrd 0.4.10 → 0.4.12

package/src/tui/usage/render.ts

@@ -585,14 +585,111 @@ function truncateNpub(npub: string): string {
   return npub.slice(0, 10) + "…" + npub.slice(-6);
 }
 
+/**
+ * Token breakdown of a single request, split the way the TUI colours it:
+ * input read from the prompt cache (green) vs input that was not (red,
+ * i.e. cache writes plus uncached input), plus output tokens.
+ */
+export interface TokenSegments {
+  /** Input tokens served from the prompt cache. */
+  cacheRead: number;
+  /** Input tokens that were not served from the cache. */
+  notCached: number;
+  /** Total input tokens, cached and not. */
+  input: number;
+  output: number;
+  /** Input + output. */
+  total: number;
+}
+
+/**
+ * Split a usage entry into cache read / not-cached input and output tokens.
+ *
+ * Providers report prompt tokens inconsistently: OpenAI-style `prompt_tokens`
+ * already includes the cached subsets, while Anthropic-style `input_tokens`
+ * reports them alongside. If the prompt is at least as large as the cached
+ * counts it is treated as containing them (OpenAI); otherwise the cached
+ * counts are extra (Anthropic). `input` is the sum of what is drawn rather
+ * than a possibly under-counted `totalTokens`.
+ */
+export function tokenSegments(entry: {
+  promptTokens?: number;
+  completionTokens?: number;
+  cacheReadInputTokens?: number;
+  cacheCreationInputTokens?: number;
+}): TokenSegments {
+  const cacheRead = Math.max(0, entry.cacheReadInputTokens || 0);
+  const cacheWrite = Math.max(0, entry.cacheCreationInputTokens || 0);
+  const prompt = Math.max(0, entry.promptTokens || 0);
+  const output = Math.max(0, entry.completionTokens || 0);
+  const cached = cacheRead + cacheWrite;
+  const uncachedInput = prompt >= cached ? prompt - cached : prompt;
+  const notCached = cacheWrite + uncachedInput;
+  const input = cacheRead + notCached;
+  return { cacheRead, notCached, input, output, total: input + output };
+}
+
+/** One coloured slice of a {@link renderStackedBar}. */
+export interface BarSegment {
+  /** Segment magnitude; negatives are treated as zero. */
+  value: number;
+  /** ANSI escape applied to this segment's cells. */
+  color: string;
+}
+
+/**
+ * Render a fixed-width stacked bar: `trackWidth` cells split between the
+ * segments in proportion to their values, so the bar conveys *composition*
+ * (magnitude is reported separately, e.g. as the token total beside it).
+ *
+ * Cell counts use largest-remainder rounding, so the segments always fill
+ * exactly `trackWidth` cells. A row with no tokens renders as an empty track.
+ */
+export function renderStackedBar(segments: BarSegment[], trackWidth: number): string {
+  const track = Math.max(0, Math.floor(trackWidth));
+  if (track === 0) return "";
+
+  const values = segments.map((segment) => Math.max(0, segment.value));
+  const total = values.reduce((sum, value) => sum + value, 0);
+  if (total <= 0) return " ".repeat(track);
+
+  const exact = values.map((value) => (value / total) * track);
+  const cells = exact.map((value) => Math.floor(value));
+  let remaining = track - cells.reduce((sum, value) => sum + value, 0);
+
+  // Largest-remainder: leftover cells go to the biggest fractional parts.
+  const remainders = exact
+    .map((value, index) => ({ index, frac: value - Math.floor(value) }))
+    .sort((a, b) => b.frac - a.frac);
+  for (let i = 0; i < remainders.length && remaining > 0; i++, remaining--) {
+    cells[remainders[i]!.index]! += 1;
+  }
+
+  const bar = segments
+    .map((segment, i) => (cells[i]! > 0 ? `${segment.color}${"█".repeat(cells[i]!)}` : ""))
+    .join("");
+  return bar.length > 0 ? bar + COLORS.reset : " ".repeat(track);
+}
+
+/** Colour coding for the Recent tab's cache-hit bars. */
+const TOKEN_BAR_COLORS = {
+  cacheRead: COLORS.green,
+  notCached: COLORS.red,
+};
+
 export function renderRecent(stats: UsageStats, width: number, naming: ClientNaming): string {
   const recentEntries = stats.entries.slice(0, 50);
   if (recentEntries.length === 0) return renderBox(["No recent entries"], width, "Recent Requests");
 
-  const timeCol = 10;
-  const modelCol = 18;
-  const tokensCol = 18;
-  const costCol = 18;
+  const timeCol = 8;
+  const costCol = 12;
+  // Width reserved left of the token counts for the cache-hit bar. `CACHE HIT`
+  // is the header drawn over the bar, so the bar can never be narrower.
+  const minBarWidth = "CACHE HIT".length;
+  const maxBarWidth = 20;
+  const minProviderCol = 12;
+  const minModelCol = 10;
+  const minClientCol = 6;
 
   // Remote mode: `Alice (claude-code)` — owner display name + the client id
   // with the `-<npub tail>` suffix stripped. Local mode (no owner/name data)
@@ -602,39 +699,81 @@ export function renderRecent(stats: UsageStats, width: number, naming: ClientNam
     hasOwnerInfo ? resolveClientLabel(entry.client, naming) : entry.client || "unknown"
   );
   const maxLabelLen = clientLabels.reduce((max, label) => Math.max(max, label.length), 6);
-  const clientCol = hasOwnerInfo ? Math.min(32, Math.max(14, maxLabelLen)) : 14;
 
-  // Budget: time + model + tokens + cost + provider + client + 5 separators.
+  // Token counts are drawn as `IN - OUT` with IN pinned to the left edge of the
+  // column and OUT to the right, so both halves need the widest value on show.
+  const tokenRows = recentEntries.map((entry) => tokenSegments(entry));
+  const inputTexts = tokenRows.map((row) => formatNumber(row.input));
+  const outputTexts = tokenRows.map((row) => formatNumber(row.output));
+  const inputCol = Math.max(...inputTexts.map((text) => text.length));
+  const outputCol = Math.max(...outputTexts.map((text) => text.length));
+  const inOutCol = inputCol + outputCol + " - ".length;
+
+  // Lay out the columns against the box's inner width: start from the widest
+  // layout, hand the slack to the provider column, then give space back in
+  // priority order (bar, provider, model, client) until everything fits.
   const innerWidth = Math.max(0, width - 4);
-  const providerCol = Math.max(12, innerWidth - timeCol - modelCol - tokensCol - costCol - 5 - clientCol);
+  let modelCol = 18;
+  let clientCol = hasOwnerInfo ? Math.min(32, Math.max(14, maxLabelLen)) : 14;
+  let barWidth = maxBarWidth;
+  let showProvider = false;
+  let providerCol = 0;
+  // Column widths plus one separator between each visible column.
+  const usedWidth = () =>
+    timeCol + modelCol + (barWidth + 1 + inOutCol) + costCol + clientCol +
+    (showProvider ? providerCol + 1 : 0) + 4;
+
+  if (innerWidth - usedWidth() > minProviderCol + 1) {
+    showProvider = true;
+    providerCol = innerWidth - usedWidth();
+  }
+  while (usedWidth() > innerWidth && barWidth > minBarWidth) barWidth -= 1;
+  while (usedWidth() > innerWidth && providerCol > minProviderCol) providerCol -= 1;
+  while (usedWidth() > innerWidth && modelCol > minModelCol) modelCol -= 1;
+  while (usedWidth() > innerWidth && clientCol > minClientCol) clientCol -= 1;
+
+  const tokensCol = barWidth + 1 + inOutCol;
 
-  const msatsToSats = (msats?: number) => typeof msats === "number" ? msats / 1000 : 0;
   const lines: string[] = [];
-  lines.push(`${COLORS.bold}${["TIME".padEnd(timeCol), "MODEL".padEnd(modelCol), "I/CR/CW/O".padEnd(tokensCol), "I/O/T in sats".padEnd(costCol), "BASE:PROVIDER".padEnd(providerCol), "CLIENT".padEnd(clientCol)].join(" ")}${COLORS.reset}`);
-  lines.push(COLORS.dim + "─".repeat(width - 4) + COLORS.reset);
+  const header = [
+    "TIME".padEnd(timeCol),
+    "MODEL".padEnd(modelCol),
+    "CACHE HIT".padEnd(tokensCol - inOutCol) + "IN".padEnd(inputCol) + " - " + "OUT".padStart(outputCol),
+    // Right-aligned like the values below it, so the column's right edge is
+    // shared by the header and every `n sats` cell.
+    "COST".padStart(costCol),
+    ...(showProvider ? ["BASE:PROVIDER".padEnd(providerCol)] : []),
+    "CLIENT".padEnd(clientCol),
+  ];
+  lines.push(`${COLORS.bold}${header.join(" ")}${COLORS.reset}`);
+  lines.push(COLORS.dim + "─".repeat(innerWidth) + COLORS.reset);
 
   for (let i = 0; i < recentEntries.length; i++) {
     const entry = recentEntries[i]!;
     const time = formatTime(entry.timestamp).slice(0, 8);
     const model = entry.modelId.slice(0, modelCol).padEnd(modelCol);
-    const tokens = [
-      entry.promptTokens,
-      entry.cacheReadInputTokens || 0,
-      entry.cacheCreationInputTokens || 0,
-      entry.completionTokens,
-    ].map(formatNumber).join("/");
+    const segments = tokenRows[i]!;
+    const bar = renderStackedBar([
+      { value: segments.cacheRead, color: TOKEN_BAR_COLORS.cacheRead },
+      { value: segments.notCached, color: TOKEN_BAR_COLORS.notCached },
+    ], barWidth);
+    const tokens = `${bar} ${inputTexts[i]!.padEnd(inputCol)} - ${outputTexts[i]!.padStart(outputCol)}`;
     const totalSats = typeof entry.totalMsats === "number" ? entry.totalMsats / 1000 : entry.satsCost;
-    const cost = [
-      formatCost(msatsToSats(entry.inputMsats)),
-      formatCost(msatsToSats(entry.outputMsats)),
-      formatCost(totalSats),
-    ].join("/");
+    // Right-aligned so the `sats` unit ends at the same column on every row.
+    const cost = `${formatCost(totalSats)} sats`.padStart(costCol);
     const baseUrl = (entry.baseUrl || "unknown").replace("https://", "").replace("http://", "");
     const provider = `${baseUrl}:${entry.provider || "unknown"}`.slice(0, providerCol).padEnd(providerCol);
     const clientLabel = clientLabels[i]!.slice(0, clientCol).padEnd(clientCol);
     const clientColor = CLIENT_COLORS[entry.client || "unknown"] || CLIENT_COLORS.default || COLORS.white;
     const modelColor = MODEL_COLORS[entry.modelId] || MODEL_COLORS.default;
-    lines.push(`${COLORS.dim}${time}${COLORS.reset} ${modelColor}${model}${COLORS.reset} ${tokens.padEnd(tokensCol)} ${COLORS.green}${cost.padEnd(costCol)}${COLORS.reset} ${COLORS.dim}${provider}${COLORS.reset} ${clientColor}${clientLabel}${COLORS.reset}`);
+    lines.push([
+      `${COLORS.dim}${time}${COLORS.reset}`,
+      `${modelColor}${model}${COLORS.reset}`,
+      tokens,
+      `${COLORS.green}${cost.padEnd(costCol)}${COLORS.reset}`,
+      ...(showProvider ? [`${COLORS.dim}${provider}${COLORS.reset}`] : []),
+      `${clientColor}${clientLabel}${COLORS.reset}`,
+    ].join(" "));
   }
 
   return renderBox(lines, width, `Recent Requests (${stats.entries.length} shown)`);

package/src/utils/config.ts

@@ -46,8 +46,9 @@ export interface RoutstrdConfig {
   port: number;
   host: string;
   provider: string | null;
-  cocodPath: string | null;
   mode?: "xcashu" | "apikeys";
+  /** Opt into SDK automatic model-path selection for DeepSeek V4.1 Flash. Disabled by default; requires daemon restart after changing. */
+  autoModelPath?: boolean;
   /** Raw upstream request/response logging. Disabled by default because logs can contain sensitive prompts, outputs, and auth/payment headers. */
   requestResponseLogging?: {
     /** Enable raw request/response file logging. */
@@ -85,7 +86,7 @@ export const DEFAULT_CONFIG: RoutstrdConfig = {
   port: 8008,
   host: "127.0.0.1",
   provider: null,
-  cocodPath: null,
   mode: "apikeys",
+  autoModelPath: false,
   maxTokens: 64000,
 };

package/src/utils/cooldowns.ts

@@ -0,0 +1,134 @@
+/**
+ * Cooldown reporting, shared by the daemon (`GET /cooldowns`) and the
+ * `routstrd cooldowns` CLI command.
+ *
+ * Cooldown state is owned by the SDK: its `ProviderManager` writes
+ * `providersOnCooldown` into the SdkStore, and every entry blocks routing for
+ * the length of the cooldown window (`getCooldownDurationMs()`, 210s today).
+ * An entry with a `modelId` cools down only that model on the provider; an
+ * entry without one cools down every model on the provider.
+ *
+ * The SDK prunes expired entries lazily (on the next routing decision), so a
+ * read of the persisted list can contain entries that already timed out.
+ * Reporting therefore filters by age and never mutates the store.
+ */
+
+/** One persisted cooldown entry, as stored by the SDK. */
+export interface StoredCooldownEntry {
+  baseUrl: string;
+  /** Present for model-scoped entries; absent for provider-wide ones. */
+  modelId?: string;
+  /** When the cooldown started (ms since epoch). */
+  timestamp: number;
+}
+
+export interface CooldownSummary {
+  baseUrl: string;
+  /** Model id for model-scoped cooldowns, `null` for provider-wide ones. */
+  modelId: string | null;
+  scope: "provider" | "model";
+  startedAt: number;
+  expiresAt: number;
+  remainingMs: number;
+}
+
+export interface CooldownsOutput {
+  /** Server time the payload was built at (ms since epoch). */
+  now: number;
+  cooldownDurationMs: number;
+  /** Number of active cooldown entries (provider- and model-scoped). */
+  count: number;
+  /** Number of distinct providers with at least one active entry. */
+  providerCount: number;
+  cooldowns: CooldownSummary[];
+}
+
+/**
+ * Build the `/cooldowns` payload: drop expired entries, tag each entry's
+ * scope, and compute when it lifts. Longest remaining cooldown comes first.
+ */
+export function buildCooldownsOutput(
+  entries: StoredCooldownEntry[],
+  cooldownDurationMs: number,
+  now: number = Date.now(),
+): CooldownsOutput {
+  const cooldowns = entries
+    .filter((entry) => now - entry.timestamp < cooldownDurationMs)
+    .map((entry): CooldownSummary => {
+      const modelId = entry.modelId ?? null;
+      const expiresAt = entry.timestamp + cooldownDurationMs;
+      return {
+        baseUrl: entry.baseUrl,
+        modelId,
+        scope: modelId === null ? "provider" : "model",
+        startedAt: entry.timestamp,
+        expiresAt,
+        remainingMs: Math.max(0, expiresAt - now),
+      };
+    })
+    .sort(
+      (a, b) =>
+        b.remainingMs - a.remainingMs ||
+        a.baseUrl.localeCompare(b.baseUrl) ||
+        (a.modelId ?? "").localeCompare(b.modelId ?? ""),
+    );
+
+  return {
+    now,
+    cooldownDurationMs,
+    count: cooldowns.length,
+    providerCount: new Set(cooldowns.map((entry) => entry.baseUrl)).size,
+    cooldowns,
+  };
+}
+
+/** Format a remaining-time value for the terminal, e.g. `2m 05s` or `42s`. */
+export function formatCooldownRemaining(ms: number): string {
+  const totalSeconds = Math.max(0, Math.ceil(ms / 1000));
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  return minutes > 0
+    ? `${minutes}m ${String(seconds).padStart(2, "0")}s`
+    : `${seconds}s`;
+}
+
+/** Render a `/cooldowns` payload for `routstrd cooldowns`. */
+export function formatCooldowns(output: CooldownsOutput): string {
+  const windowSeconds = Math.round(output.cooldownDurationMs / 1000);
+  const heading = `Cooldowns (${windowSeconds}s window)`;
+
+  if (output.cooldowns.length === 0) {
+    return `${heading}\n\n  Nothing is on cooldown right now.`;
+  }
+
+  const scopeCell = (entry: CooldownSummary) =>
+    entry.scope === "provider" ? "PROVIDER" : "MODEL";
+  const urlWidth = Math.max(
+    ...output.cooldowns.map((entry) => entry.baseUrl.length),
+  );
+  const modelWidth = Math.max(
+    0,
+    ...output.cooldowns.map((entry) => (entry.modelId ?? "").length),
+  );
+
+  const lines = [
+    heading,
+    "",
+    `  ${output.count} active across ${output.providerCount} ${
+      output.providerCount === 1 ? "provider" : "providers"
+    }:`,
+    "",
+  ];
+
+  for (const entry of output.cooldowns) {
+    const cells = [scopeCell(entry).padEnd("PROVIDER".length), entry.baseUrl.padEnd(urlWidth)];
+    if (entry.scope === "model") {
+      cells.push((entry.modelId ?? "").padEnd(modelWidth));
+    }
+    lines.push(
+      `  ${cells.join("  ")}  expires in ${formatCooldownRemaining(entry.remainingMs)}`,
+    );
+  }
+
+  return lines.join("\n");
+}

package/src/utils/daemon-client.ts

@@ -56,6 +56,32 @@ class DaemonConnectionError extends Error {
   }
 }
 
+/**
+ * Upper bound for a single daemon request, including response-body
+ * consumption. The daemon bounds its own NWC operations, so this only guards
+ * against a wedged server; without it a hung request would block the CLI
+ * forever.
+ */
+export const DAEMON_REQUEST_TIMEOUT_MS = 120_000;
+
+/**
+ * Upper bound for value-moving wallet routes. A cashu melt/swap can
+ * legitimately run longer than {@link DAEMON_REQUEST_TIMEOUT_MS} (the mint has
+ * no request timeout in routstrd), so these get a more generous bound that
+ * still prevents an indefinite CLI hang.
+ */
+export const DAEMON_LONG_REQUEST_TIMEOUT_MS = 600_000;
+
+/** Routes that may legitimately outlive the default request timeout. */
+const LONG_RUNNING_ROUTES = ["/wallet/send/", "/wallet/receive/"];
+
+function requestTimeoutMs(path: string): number {
+  const pathname = path.split("?")[0] ?? path;
+  return LONG_RUNNING_ROUTES.some((route) => pathname.startsWith(route))
+    ? DAEMON_LONG_REQUEST_TIMEOUT_MS
+    : DAEMON_REQUEST_TIMEOUT_MS;
+}
+
 export function getDaemonBaseUrl(config: RoutstrdConfig): string {
   if (config.daemonUrl) {
     return config.daemonUrl.replace(/\/$/, "");
@@ -70,7 +96,7 @@ export function getAuthBaseUrl(config: RoutstrdConfig): string {
   return getDaemonBaseUrl(config);
 }
 
-async function _callUrl(
+export async function callDaemonUrl(
   baseUrl: string,
   path: string,
   options: { method?: "GET" | "POST" | "PATCH" | "DELETE"; body?: object },
@@ -99,23 +125,41 @@ async function _callUrl(
   if (authorization) headers.set("Authorization", authorization);
   if (bodyString) headers.set("Content-Type", "application/json");
 
+  const timeoutMs = requestTimeoutMs(path);
+  const timeoutError = () =>
+    new Error(
+      `Daemon request timed out after ${timeoutMs / 1000}s; ` +
+        "any payment outcome is unknown — check before retrying",
+    );
+  // The signal stays armed while the body is read, so a daemon that sends
+  // headers and then stalls the body cannot hang the CLI either. Aborting
+  // here never cancels the daemon's operation — see timeoutError's warning.
+  const signal = AbortSignal.timeout(timeoutMs);
+
   let response: Response;
   try {
     response = await fetch(url, {
       method,
       headers,
       body: bodyString,
+      signal,
     });
   } catch (error) {
+    if (signal.aborted) throw timeoutError();
+    // Only connection failures qualify for alternate-host retries.
     throw new DaemonConnectionError(error);
   }
 
-  if (!response.ok) {
-    const errorData = (await response.json()) as { error?: string };
-    throw new Error(errorData.error || `HTTP ${response.status}`);
+  try {
+    if (!response.ok) {
+      const errorData = (await response.json()) as { error?: string };
+      throw new Error(errorData.error || `HTTP ${response.status}`);
+    }
+    return (await response.json()) as CommandResponse;
+  } catch (error) {
+    if (signal.aborted) throw timeoutError();
+    throw error;
   }
-
-  return response.json() as Promise<CommandResponse>;
 }
 
 async function callLocalDaemon(
@@ -127,7 +171,7 @@ async function callLocalDaemon(
   let connectionError: DaemonConnectionError | undefined;
   for (const baseUrl of localDaemonBaseUrls(config)) {
     try {
-      return await _callUrl(baseUrl, path, options, config);
+      return await callDaemonUrl(baseUrl, path, options, config);
     } catch (error) {
       if (!(error instanceof DaemonConnectionError)) throw error;
       connectionError = error;
@@ -142,7 +186,7 @@ export async function callDaemon(
 ): Promise<CommandResponse> {
   const config = await loadConfig();
   if (config.daemonUrl) {
-    return _callUrl(getDaemonBaseUrl(config), path, options, config);
+    return callDaemonUrl(getDaemonBaseUrl(config), path, options, config);
   }
   return callLocalDaemon(path, options, config);
 }
@@ -157,7 +201,7 @@ export async function callAuth(
   if (!config.authUrl && !config.daemonUrl) {
     return callLocalDaemon(path, options, config);
   }
-  return _callUrl(getAuthBaseUrl(config), path, options, config);
+  return callDaemonUrl(getAuthBaseUrl(config), path, options, config);
 }
 
 export async function isDaemonRunning(): Promise<boolean> {

package/src/utils/history.ts

@@ -0,0 +1,9 @@
+/** Transaction types understood by the wallet history type filter. */
+export const HISTORY_ENTRY_TYPES = ["mint", "melt", "send", "receive"] as const;
+
+export type HistoryEntryType = (typeof HISTORY_ENTRY_TYPES)[number];
+
+/** True when `value` is a recognized history transaction type. */
+export function isHistoryEntryType(value: string): value is HistoryEntryType {
+  return (HISTORY_ENTRY_TYPES as readonly string[]).includes(value);
+}

package/src/utils/with-timeout.ts

@@ -0,0 +1,21 @@
+/**
+ * Rejects when `timeoutMs` elapses before `promise` settles.
+ * This bounds the caller's wait; it does not cancel the underlying operation.
+ *
+ * Used to bound requests that may otherwise wait forever — notably NWC calls
+ * whose underlying library applies its own timeout only after a support/encryption
+ * handshake that can itself hang on a stale relay subscription.
+ */
+export function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  message = "Operation timed out",
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => reject(new Error(message)), timeoutMs);
+  });
+  return Promise.race([promise, timeout]).finally(() => {
+    if (timer !== undefined) clearTimeout(timer);
+  });
+}

package/src/TUI refactor.md

@@ -1,113 +0,0 @@
-# TUI refactor plan
-
-## Goals
-- Move the usage TUI implementation out of `src/cli/usage-tui.ts` into a dedicated `src/tui/` folder.
-- Reduce the size and responsibility of the current monolithic file.
-- Keep the existing CLI entrypoint stable so current usage does not break.
-- Preserve behavior while making future TUI work easier.
-
-## Current state
-`src/cli/usage-tui.ts` currently mixes several concerns in one file:
-- TUI-specific types and constants
-- ANSI/terminal helpers
-- scroll/search/vim navigation state
-- data fetching from the daemon
-- usage aggregation/stat helpers
-- rendering for all tabs
-- app lifecycle and keyboard event handling
-
-This makes the file hard to extend safely.
-
-## Refactor strategy
-Do this incrementally and keep a thin compatibility wrapper in `src/cli/usage-tui.ts`.
-
-### Target structure
-- `src/tui/usage/index.ts`
-  - public entrypoint: `runUsageTui()`
-- `src/tui/usage/types.ts`
-  - `UsageStats`, tab ids, tab metadata, derived stat types
-- `src/tui/usage/constants.ts`
-  - tabs, colors, model/client color maps
-- `src/tui/usage/terminal.ts`
-  - ANSI helpers, width/height helpers, `stripAnsi`
-- `src/tui/usage/state.ts`
-  - vim/search/scroll state and state mutation helpers
-- `src/tui/usage/data.ts`
-  - `fetchUsage()` and usage aggregation helpers
-- `src/tui/usage/render.ts`
-  - shared render helpers and tab renderers
-- `src/tui/usage/app.ts`
-  - main loop, render orchestration, input handling, cleanup
-- `src/cli/usage-tui.ts`
-  - compatibility wrapper that re-exports or calls `runUsageTui()` from `src/tui/usage`
-
-## Design choices
-### 1. Keep CLI path compatibility
-Do not delete the CLI file outright. Turn it into a tiny wrapper:
-- minimal import from `../tui/usage/index.ts`
-- export `runUsageTui()`
-
-This avoids breaking any existing imports or scripts.
-
-### 2. Separate pure logic from side effects
-Keep these pure where possible:
-- aggregation helpers
-- formatting helpers
-- render helpers that return strings
-- scroll clamping logic
-
-Keep side effects isolated in the app layer:
-- reading terminal size
-- writing to stdout
-- raw mode setup
-- signal handling
-- interval scheduling
-
-### 3. Avoid over-engineering
-This should be a pragmatic refactor, not a framework:
-- no unnecessary classes
-- keep function-based design
-- only extract modules around clear responsibility boundaries
-
-### 4. Preserve behavior first
-No UX changes unless needed to support the extraction.
-That means:
-- same tabs
-- same keybindings
-- same output format
-- same fetch cadence
-- same search/scroll behavior
-
-## Implementation steps
-1. Create `src/tui/usage/`.
-2. Extract types/constants first.
-3. Extract terminal helpers.
-4. Extract data fetching + aggregation helpers.
-5. Extract state/search/scroll logic.
-6. Extract rendering helpers + tab renderers.
-7. Build `app.ts` using the extracted modules.
-8. Replace `src/cli/usage-tui.ts` with a thin wrapper.
-9. Run a TypeScript/bun check and fix imports.
-10. Smoke-test keyboard handling and rendering behavior.
-
-## Risks
-- circular imports between render/state/constants
-- broken relative import paths during extraction
-- subtle behavior regressions in scroll/search state
-- terminal escape handling differences if helpers are split carelessly
-
-## Validation checklist
-- `src/cli/usage-tui.ts` still exposes `runUsageTui()`
-- TUI starts from the same CLI path
-- scroll still works for long content
-- vim keys still work
-- arrow keys still work
-- tab switching still resets scroll
-- search mode still works
-- cleanup still restores cursor and alternate screen
-
-## Non-goals
-- redesigning the UI
-- changing tab contents
-- introducing tests unless needed for safety
-- adding new features unrelated to the refactor