@hncode/hncode 0.4.2 → 0.5.0

package/src/file-history.js

@@ -175,3 +175,115 @@ export function describeRewind(res) {
   if (res.failed.length) parts.push(`${res.failed.length} could not be restored`);
   return parts.join(', ');
 }
+
+/**
+ * Every checkpoint on record, newest turn first, as one flat list.
+ *
+ * WHY THIS EXISTS BESIDE `rewind`
+ * -------------------------------
+ * `rewind(n)` is all-or-nothing across whole turns: to get one file back you must also roll
+ * back every other file those turns touched. That is the right default (a turn is a unit of
+ * intent) and the wrong tool for "I want the version of THIS file from before that one
+ * edit". The index already records exactly that — one entry per file per turn, with the
+ * content it had — so the list is a rearrangement of existing data, not new bookkeeping.
+ *
+ * @returns {Array<{turn:number, at:number, path:string, existed:boolean, backup:string,
+ *   size:number|null, ageMs:number}>} turn is 1-based, counting from the oldest.
+ */
+export function listCheckpoints(sessionId, opts = {}) {
+  const doc = readIndex(sessionId);
+  const only = opts.path ? path.resolve(opts.path) : null;
+  const out = [];
+  const now = Date.now();
+  for (let i = doc.turns.length - 1; i >= 0; i--) {
+    const turn = doc.turns[i];
+    for (const f of turn.files) {
+      if (only && f.path !== only) continue;
+      let size = null;
+      if (f.existed && f.backup) {
+        try { size = fs.statSync(f.backup).size; } catch { size = null; }
+      }
+      out.push({
+        // `index` is 1-based over the whole list, newest first — the number the panel
+        // prints and `restore <n>` accepts. Assigned here rather than derived from `turn`
+        // so a row keeps its identity even after another turn is recorded.
+        index: 0,
+        turn: i + 1,
+        at: turn.at,
+        path: f.path,
+        existed: f.existed !== false,
+        backup: f.backup || '',
+        size,
+        ageMs: Math.max(0, now - (turn.at || now)),
+      });
+    }
+  }
+  out.forEach((c, i) => { c.index = i + 1; });
+  return out;
+}
+
+/**
+ * Restore ONE file from one checkpoint, leaving every other file and the turn index alone.
+ *
+ * The index is deliberately NOT truncated: this is a surgical restore, not a rewind, so the
+ * remaining checkpoints stay valid. A file that did not exist at that checkpoint is deleted,
+ * which is what "restore" means for a file the agent created.
+ *
+ * @returns {{ok: boolean, action?: 'restored'|'deleted', error?: string}}
+ */
+export function restoreCheckpoint(sessionId, entry) {
+  const target = entry && entry.path;
+  if (!target) return { ok: false, error: 'no path on that checkpoint' };
+  try {
+    if (entry.existed === false) {
+      fs.rmSync(target, { force: true });
+      return { ok: true, action: 'deleted' };
+    }
+    if (!entry.backup) return { ok: false, error: 'that checkpoint has no content copy' };
+    // Read BEFORE creating the directory: a missing backup must not leave an empty
+    // directory behind where there was none.
+    const content = fs.readFileSync(entry.backup);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, content);
+    return { ok: true, action: 'restored' };
+  } catch (e) {
+    return { ok: false, error: e && e.message ? e.message : String(e) };
+  }
+}
+
+/** A `+N -M` size delta for a checkpoint against the current file, or null when either side
+ *  is unavailable. Cheap: it reads only the backup (the current file is stat'ed). */
+export function checkpointDelta(entry) {
+  if (!entry || !entry.existed || !entry.backup) return null;
+  try {
+    const before = fs.readFileSync(entry.backup, 'utf8').split(/\r?\n/).length;
+    const after = fs.readFileSync(entry.path, 'utf8').split(/\r?\n/).length;
+    return { before, after, lines: after - before };
+  } catch { return null; }
+}
+
+/** Lines for the /checkpoints panel: one row per checkpoint, grouped visually by turn. */
+export function describeCheckpoints(sessionId, workspace) {
+  const all = listCheckpoints(sessionId);
+  if (!all.length) {
+    return ['No checkpoints recorded for this session yet.', '',
+      'A checkpoint is taken the first time the agent changes a file in a turn,',
+      'so this fills in as you work.'];
+  }
+  const lines = [`Checkpoints (${all.length}) across ${new Set(all.map((c) => c.turn)).size} turn(s)`, ''];
+  let lastTurn = null;
+  for (const c of all) {
+    if (c.turn !== lastTurn) {
+      lastTurn = c.turn;
+      const when = c.at ? new Date(c.at).toISOString().slice(0, 16).replace('T', ' ') : '?';
+      lines.push(`turn ${c.turn}  ${when}`);
+    }
+    const rel = workspace && String(c.path).startsWith(workspace)
+      ? path.relative(workspace, c.path).split(path.sep).join('/')
+      : c.path;
+    const what = c.existed ? `${c.size == null ? '?' : c.size} B` : 'created here';
+    lines.push(`  ${String(c.index).padStart(3)}  ${what.padEnd(12)} ${rel}`);
+  }
+  lines.push('', 'Restore one with /checkpoints restore <n>');
+  return lines;
+}

package/src/file-tree.js

@@ -0,0 +1,255 @@
+// File tree browser — a navigable view of the workspace, opened with /files.
+//
+// WHY A TREE AND NOT A PICKER
+// ---------------------------
+// The picker is a flat, filtered list: good for "find me this one file" and bad for
+// "what is in here". Reading a project's shape is a question the flat list cannot answer,
+// because it has no directories — every path is a string, and the structure is only
+// visible by reading the prefixes. This module renders the structure itself.
+//
+// WHY IT DOES NOT RE-IMPLEMENT THE WALK
+// -------------------------------------
+// `tools/ignore.js` already walks a tree honouring .gitignore/.hncodeignore, including
+// negation patterns and subtree pruning, and it is what Grep and Glob use. A second walker
+// here would drift: the browser would show files the tools refuse to search, which is
+// worse than no browser. So this module takes a LIST OF PATHS and only arranges it.
+//
+// WHY THE DIRECTORIES ARE DERIVED, NOT WALKED
+// -------------------------------------------
+// `walkFiles` returns files. The directories in between are reconstructed from the paths,
+// which means the tree can never disagree with the list it came from — and it costs one
+// pass over a flat array rather than a second filesystem traversal.
+
+import path from 'node:path';
+import { C } from './colors.js';
+import { visualWidth } from './term.js';
+
+const ELLIPSIS = '\u2026';
+const ESC = '\x1b';
+
+function visWidth(s) { return visualWidth(String(s).replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, '')); }
+function col(text, c) { return c + String(text) + C.reset; }
+
+/**
+ * Build a directory tree from a flat list of absolute paths.
+ *
+ * @param {string[]} files absolute paths, as `walkFiles` returns them
+ * @param {string} root the workspace root they are relative to
+ * @returns {{name:string, rel:string, dir:boolean, children:Array}} the root node
+ *
+ * Children are sorted DIRECTORIES FIRST, then names, which is what makes a tree readable:
+ * a mixed sort buries directories among files and the structure stops being visible.
+ */
+export function buildTree(files, root) {
+  const base = path.resolve(root);
+  const rootNode = { name: path.basename(base) || base, rel: '', dir: true, children: [] };
+  // One map per directory level, keyed by relative path, so a directory is created once
+  // no matter how many files sit under it.
+  const dirs = new Map([['', rootNode]]);
+
+  function ensureDir(rel) {
+    if (dirs.has(rel)) return dirs.get(rel);
+    const parentRel = rel.includes('/') ? rel.slice(0, rel.lastIndexOf('/')) : '';
+    const parent = ensureDir(parentRel);
+    const node = { name: rel.slice(rel.lastIndexOf('/') + 1), rel, dir: true, children: [] };
+    parent.children.push(node);
+    dirs.set(rel, node);
+    return node;
+  }
+
+  for (const abs of files) {
+    let rel = path.relative(base, abs);
+    if (!rel || rel.startsWith('..')) continue;         // outside the root: not ours to show
+    rel = rel.split(path.sep).join('/');
+    const parentRel = rel.includes('/') ? rel.slice(0, rel.lastIndexOf('/')) : '';
+    const parent = ensureDir(parentRel);
+    parent.children.push({
+      name: rel.slice(rel.lastIndexOf('/') + 1), rel, dir: false, children: [],
+    });
+  }
+  sortTree(rootNode);
+  return rootNode;
+}
+
+function sortTree(node) {
+  if (!node.children.length) return;
+  node.children.sort((a, b) => {
+    if (a.dir !== b.dir) return a.dir ? -1 : 1;
+    return a.name.localeCompare(b.name);
+  });
+  for (const c of node.children) if (c.dir) sortTree(c);
+}
+
+/**
+ * Flatten the tree to the rows the panel draws, honouring which directories are open.
+ *
+ * `expanded` is a Set of relative directory paths. It is the caller's state, not this
+ * module's: a browser that owned its own open/closed set could not be reopened where the
+ * user left it, and could not be driven by a test.
+ *
+ * @returns {Array<{node:object, depth:number, last:boolean, prefix:string}>}
+ *   `prefix` carries the box-drawing gutter (`│  ` / `   `) built from the ancestors.
+ */
+export function visibleRows(root, expanded, depth = 0, prefix = '', last = true, out = []) {
+  for (let i = 0; i < root.children.length; i++) {
+    const node = root.children[i];
+    const isLast = i === root.children.length - 1;
+    out.push({ node, depth, last: isLast, prefix });
+    if (node.dir && expanded.has(node.rel)) {
+      // The gutter for a child: a vertical bar while this node still has siblings below
+      // it, spaces once it does not — that is what makes the lines reach the right parent.
+      const next = prefix + (isLast ? '   ' : '\u2502  ');
+      visibleRows(node, expanded, depth + 1, next, isLast, out);
+    }
+  }
+  return out;
+}
+
+/** Every directory path in the tree, so the caller can "expand all" without a walk of its own. */
+export function allDirs(root, out = []) {
+  for (const c of root.children) {
+    if (c.dir) { out.push(c.rel); allDirs(c, out); }
+  }
+  return out;
+}
+
+/** Count the files under a node, for the `(N)` after a directory name. */
+export function countFiles(node) {
+  if (!node.dir) return 1;
+  let n = 0;
+  for (const c of node.children) n += countFiles(c);
+  return n;
+}
+
+/**
+ * Render the browser.
+ *
+ * @param {object} input
+ * @param {object} input.root       from buildTree
+ * @param {Array}  input.rows       from visibleRows
+ * @param {number} input.sel        selected index into `rows`
+ * @param {number} input.scroll     first visible row
+ * @param {number} input.width
+ * @param {number} input.height     rows available to the panel
+ * @param {string} [input.filter]   substring the file list was narrowed by
+ * @param {string} [input.cwd]
+ * @returns {{ lines: string[], sel: number, scroll: number, hitRows: Array }}
+ */
+export function renderTree(input) {
+  const {
+    root, rows, width, height, cwd = '',
+  } = input;
+  const filter = String(input.filter || '');
+  // The caller's width is RESPECTED, not raised to a minimum: a row wider than the frame
+  // wraps and corrupts every row under it, so a floor here would be a bug, not a courtesy.
+  const w = Math.max(1, width | 0);
+  // Header (2) + footer (1) come out of the budget; a body of at least one row.
+  const bodyH = Math.max(1, (height | 0) - 3);
+
+  let sel = Math.max(0, Math.min((input.sel | 0), Math.max(0, rows.length - 1)));
+  let scroll = Math.max(0, input.scroll | 0);
+  if (sel < scroll) scroll = sel;
+  if (sel >= scroll + bodyH) scroll = sel - bodyH + 1;
+
+  const total = root.children.length ? countFiles(root) : 0;
+  const title = filter
+    ? `Files matching "${filter}" — ${total} file(s)`
+    : `Files — ${total} file(s)`;
+  // Deliberately terse: the full phrasing ("↑↓ move · →/← open/close · Enter insert path ·
+  // Ctrl+O expand all · Esc close") is 71 columns and got clipped mid-word at 70.
+  const hint = '↑↓ move · →/← open · Enter insert · Ctrl+O all · Esc close';
+
+  const lines = [];
+  // The header and the hint are clamped to the panel like every other row. Unclamped, a
+  // narrow terminal pushed them past the width and the whole frame wrapped.
+  lines.push(col(truncate(' ' + title, w), C.white + C.bold));
+  lines.push(col(truncate(' ' + hint, w), C.gray));
+
+  const hitRows = [];
+  const shown = rows.slice(scroll, scroll + bodyH);
+  for (let i = 0; i < shown.length; i++) {
+    const { node, prefix } = shown[i];
+    const index = scroll + i;
+    const selected = index === sel;
+    const marker = node.dir ? (input.expandedSet && input.expandedSet.has(node.rel) ? '\u25be' : '\u25b8') : ' ';
+    const label = node.dir ? `${node.name}/` : node.name;
+    const lead = ` ${prefix}${marker} `;
+    const leadW = visWidth(lead);
+    // Budget for the name, AFTER the gutter and the marker. Measured in VISUAL columns,
+    // not characters: `slice` counts code units, so a name with a wide character or an
+    // escape in it would come out wider than asked and wrap the whole frame.
+    const suffixText = node.dir ? `  (${countFiles(node)})` : '';
+    const suffixW = visWidth(suffixText);
+    let room = Math.max(1, w - leadW - 1);
+    // The count is a NICER label than a longer name, so it is dropped only when keeping it
+    // would truncate the name to nothing.
+    const showSuffix = suffixW > 0 && room - suffixW >= 8;
+    if (showSuffix) room -= suffixW;
+    const cut = clipToWidth(label, room);
+    const text = lead + col(cut, selected ? C.hover : (node.dir ? C.cyan : C.fg))
+      + (showSuffix ? col(suffixText, C.gray) : '');
+    // A selected row is painted full-width so the highlight is a band, not a word.
+    lines.push(selected ? padRight(text, w) : text);
+    if (selected) {
+      // The caller needs the row index to map a click back to this node.
+      hitRows.push(index);
+    }
+  }
+  // Pad the body out so the panel is a solid block rather than a ragged one.
+  // Pad the body out so the panel is a solid block rather than a ragged one.
+  while (lines.length < bodyH + 2) lines.push(' '.repeat(w));
+
+  const pos = rows.length ? `${sel + 1}/${rows.length}` : '0/0';
+  // A row is `{ node, depth, prefix }`, NOT the node itself — reading `.rel` off the row
+  // silently produced an empty path, so the footer showed only the position.
+  const cur = rows[sel];
+  const rel = cur && cur.node ? cur.node.rel : '';
+  const footer = ` ${pos}  ${rel}`;
+  lines.push(col(truncate(footer, w), C.gray));
+
+  return { lines, sel, scroll, hitRows };
+}
+
+function truncate(s, w) {
+  const str = String(s);
+  if (visWidth(str) <= w) return str;
+  return clipToWidth(str, w);
+}
+
+/**
+ * Clip a string to at most `w` VISUAL columns, ending with an ellipsis when it was cut.
+ *
+ * `slice` cannot do this: it counts UTF-16 code units, so a name with a wide character in
+ * it comes out wider than the budget and wraps the row it was supposed to fit.
+ */
+function clipToWidth(s, w) {
+  const str = String(s);
+  if (w <= 0) return '';
+  if (visWidth(str) <= w) return str;
+  let out = '';
+  let n = 0;
+  for (const ch of str) {
+    const cw = visWidth(ch);
+    if (n + cw > w - 1) break;
+    n += cw;
+    out += ch;
+  }
+  return out + ELLIPSIS;
+}
+
+function padRight(s, w) {
+  const have = visWidth(s);
+  return have >= w ? s : s + ' '.repeat(w - have);
+}
+
+/**
+ * The next selection when moving by `delta`, skipping nothing.
+ *
+ * Kept as a function rather than inline arithmetic so the wrap-around rule is stated once:
+ * the list WRAPS, because a browser that dead-ends at the bottom makes the arrow keys feel
+ * broken on a short list.
+ */
+export function moveSel(sel, delta, count) {
+  if (!count) return 0;
+  return ((sel + delta) % count + count) % count;
+}

package/src/flush-tick.js

@@ -0,0 +1,56 @@
+// Monotonic terminal-flush counter.
+//
+// WHY THIS EXISTS
+// ---------------
+// "I changed the state" and "the terminal has that change" are different facts, and
+// this TUI has code that conflates them.
+//
+// State changes reach the screen through `renderSoon()`, which only SCHEDULES a paint
+// (`setImmediate`). Several places then read the screen's geometry back as if the paint
+// had already happened: the mouse handlers map a click's row to a transcript line
+// through `state._bodyScreenTop`, the transcript renderer anchors the scroll position to
+// `state._anchorPin`, and a resize defers its repair to the next frame. Every one of
+// those is computed by `composeFrame` — the same call the pending paint will make, with
+// the same state, so the values agree. The fragile part is not the arithmetic, it is the
+// ORDERING: any of them can run in the window between the state change and the paint,
+// and if the paint is then superseded (a resize, a re-entrant render) the value that was
+// acted upon belongs to a frame that never reached the terminal.
+//
+// A counter makes "a frame has been written" observable, which is what lets a caller
+// wait for it instead of assuming it. Deliberately a plain module-level integer with no
+// allocation and no subscriber list: it is read a handful of times per frame, not
+// subscribed to.
+
+let flushTick = 0;
+
+/**
+ * Record one completed terminal frame write. Called from the single place every screen
+ * change passes through, so "the tick advanced" means bytes left this process.
+ *
+ * Advanced even when a frame produced NO output (`diffFrame` returned an empty string
+ * when nothing changed): a frame that was correctly painted by writing nothing is just
+ * as painted, and gating on the tick would then wait for a change that will never come.
+ */
+export function noteTerminalFlush() {
+  flushTick++;
+  return flushTick;
+}
+
+/** The current tick. Monotonic for the life of the process; never resets. */
+export function getTerminalFlushTick() {
+  return flushTick;
+}
+
+/**
+ * True once a frame has been written SINCE the given tick was taken.
+ *
+ * The usage that matters is "I am about to change state that is only observable after a
+ * paint; if a paint already happened since I looked, the value I would read is current,
+ * and if not, it is stale." Callers capture `getTerminalFlushTick()` when they widen a
+ * value (open a panel, start a drag) and use this to decide whether to re-read it.
+ *
+ * @param {number} since a tick from `getTerminalFlushTick`.
+ */
+export function frameWrittenSince(since) {
+  return flushTick !== since;
+}

package/src/fork.js

@@ -0,0 +1,44 @@
+/**
+ * A message that belongs to ONE conversation.
+ *
+ * `/fork` used `messages.slice()`, which copies the array but not the messages in it, so
+ * the fork and its parent shared every message object. Nothing went wrong until the
+ * fork edited one — then the parent changed too, in a session the user had already
+ * walked away from. A shallow copy of the message is the minimum; the nested fields are
+ * copied as well because a turn writes into them (`toolCalls`, a growing `content`
+ * string on a streamed assistant message, the `allLines` of a plugin log).
+ *
+ * The underscore-prefixed bookkeeping fields are NOT copied: they describe the parent’s
+ * render state, and carrying them over would make the fork display rows the new
+ * conversation has not produced.
+ */
+export function cloneMessageForFork(m) {
+  if (!m || typeof m !== 'object') return m;
+  const copy = {};
+  for (const k of Object.keys(m)) {
+    // Render bookkeeping: the fork has its own screen and its own scroll.
+    if (k === '_conv' || k === '_mdCache' || k === '_wrapped' || k === '_prevWrap') continue;
+    const v = m[k];
+    if (Array.isArray(v)) copy[k] = v.map((e) => (e && typeof e === 'object' ? { ...e } : e));
+    else if (v && typeof v === 'object') copy[k] = { ...v };
+    else copy[k] = v;
+  }
+  return copy;
+}
+// The command that uses it: `/fork`. Kept beside the clone so the two cannot drift.
+//
+export function forkOf(session, newId, now = Date.now()) {
+  const forked = {
+    ...session,
+    id: newId(),
+    title: `${session.title || 'untitled'} (fork)`,
+    createdAt: now,
+    updatedAt: now,
+    messages: (session.messages || []).map(cloneMessageForFork),
+    forkedFrom: session.forkedFrom || session.id || null,
+  };
+  // The turn counters belong to the conversation, not to the copy.
+  delete forked.rounds;
+  delete forked.steps;
+  return forked;
+}

package/src/fx.js

@@ -0,0 +1,148 @@
+// Currency conversion for the cost readout, so /cost can report in CNY as well
+// as USD. Prices from models.dev are USD per 1M tokens; a Chinese user wants to
+// see what that came to in ￥, and doing that by hand every time is the reason
+// nobody looks at the number.
+//
+// Three ways to get the rate, in order:
+//   1. an explicit override — `cny_per_usd` in config.toml, or HNCODE_CNY_PER_USD
+//      in the environment. Checked first and used with NO network call, so a
+//      machine without internet still reports a correct ￥ figure.
+//   2. a live fetch from a keyless reference-rate API, memoized for HOURS: the
+//      rate moves a fraction of a percent a day, and this only feeds a readout.
+//   3. nothing. The caller then says the rate is unavailable rather than
+//      converting with a guessed 7.0, which would be wrong in a way the user
+//      cannot see.
+//
+// Endpoints are tried in order because neither is guaranteed: frankfurter
+// republishes ECB reference rates (stable, but ECB-only currencies), and
+// open.er-api.com covers more currencies without a key.
+
+const TTL_MS = 6 * 60 * 60 * 1000;
+
+// currency -> { rate, source, at }. A plain Map, so a test can inspect or clear it.
+const cache = new Map();
+
+/** Currencies /cost accepts. USD is the native one (models.dev prices in it). */
+export const SUPPORTED_CURRENCIES = ['USD', 'CNY'];
+
+/** `'cny'`/`'￥'` -> `'CNY'`; returns '' when unrecognised. */
+export function normalizeCurrency(value) {
+  const s = String(value == null ? '' : value).trim().toUpperCase();
+  if (!s) return '';
+  if (s === '¥' || s === '￥' || s === 'RMB' || s === 'YUAN') return 'CNY';
+  if (s === '$' || s === 'USD' || s === 'US$') return 'USD';
+  return SUPPORTED_CURRENCIES.includes(s) ? s : '';
+}
+
+/**
+ * Pull the USD->`currency` rate out of either API's response shape:
+ *   frankfurter      { amount: 1, base: 'USD', rates: { CNY: 6.70 } }
+ *   open-er-api      { result: 'success', base_code: 'USD', conversion_rates: { CNY: 7.12 } }
+ * Returns a positive number, or null when the payload has no usable rate.
+ */
+export function parseRate(json, currency = 'CNY') {
+  if (!json || typeof json !== 'object') return null;
+  const key = normalizeCurrency(currency) || 'CNY';
+  const table = json.rates || json.conversion_rates;
+  if (!table || typeof table !== 'object') return null;
+  const raw = table[key];
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+/** USD -> `currency` at `rate`. Null when either input is unusable. */
+export function convert(usd, currency, rate) {
+  const amount = Number(usd);
+  if (!Number.isFinite(amount)) return null;
+  const cur = normalizeCurrency(currency) || 'USD';
+  if (cur === 'USD') return amount;               // no rate needed
+  const r = Number(rate);
+  if (!Number.isFinite(r) || r <= 0) return null;
+  return amount * r;
+}
+
+/** The `<CUR>_PER_USD` env override, or null. Both the short and prefixed names. */
+export function envRate(currency) {
+  const cur = normalizeCurrency(currency);
+  if (!cur || cur === 'USD') return null;
+  for (const key of [`HNCODE_${cur}_PER_USD`, `HNCODE_${cur}_RATE`]) {
+    const n = Number(process.env[key]);
+    if (Number.isFinite(n) && n > 0) return { rate: n, source: key };
+  }
+  return null;
+}
+
+const ENDPOINTS = [
+  { source: 'frankfurter (ECB)', url: (cur) => `https://api.frankfurter.app/latest?from=USD&to=${cur}` },
+  { source: 'open.er-api.com', url: () => 'https://open.er-api.com/v6/latest/USD' },
+];
+
+/**
+ * USD -> `currency` rate.
+ *
+ * `opts.override` is a user-set rate (config.toml); it wins over the network.
+ * `opts.timeoutMs` bounds each request. Returns
+ * `{ rate, source, at }`, or null when nothing could supply one.
+ */
+export async function usdRate(currency, opts = {}) {
+  const cur = normalizeCurrency(currency);
+  if (!cur || cur === 'USD') return { rate: 1, source: 'native', at: Date.now() };
+
+  const override = Number(opts.override);
+  if (Number.isFinite(override) && override > 0) return { rate: override, source: 'config', at: Date.now() };
+  const fromEnv = envRate(cur);
+  if (fromEnv) return { ...fromEnv, at: Date.now() };
+
+  const hit = cache.get(cur);
+  if (hit && Date.now() - hit.at < TTL_MS) return hit;
+
+  for (const ep of ENDPOINTS) {
+    try {
+      const ctrl = new AbortController();
+      const timer = setTimeout(() => ctrl.abort(), opts.timeoutMs || 8000);
+      let json;
+      try {
+        const res = await fetch(ep.url(cur), { signal: ctrl.signal, headers: { accept: 'application/json' } });
+        if (!res.ok) continue;
+        json = await res.json();
+      } finally {
+        clearTimeout(timer);
+      }
+      const rate = parseRate(json, cur);
+      if (rate) {
+        const entry = { rate, source: ep.source, at: Date.now() };
+        cache.set(cur, entry);
+        return entry;
+      }
+    } catch { /* offline or blocked: try the next endpoint */ }
+  }
+  return null;
+}
+
+/**
+ * The rate WITHOUT touching the network: an explicit override, the environment,
+ * or a still-fresh memoized value. Returns null when the answer would require a
+ * request.
+ *
+ * This exists because the status row is drawn from a SYNCHRONOUS render function,
+ * which cannot await a fetch. The rate therefore has to be warmed ahead of time
+ * (see the TUI's startup and /cost) and read here; a missing rate means the row
+ * falls back to USD rather than blocking or showing a converted guess.
+ */
+export function syncRate(currency, opts = {}) {
+  const cur = normalizeCurrency(currency);
+  if (!cur) return null;
+  if (cur === 'USD') return { rate: 1, source: 'native', at: Date.now() };
+  const override = Number(opts.override);
+  if (Number.isFinite(override) && override > 0) return { rate: override, source: 'config', at: Date.now() };
+  const fromEnv = envRate(cur);
+  if (fromEnv) return { ...fromEnv, at: Date.now() };
+  const hit = cache.get(cur);
+  return (hit && Date.now() - hit.at < TTL_MS) ? hit : null;
+}
+
+
+/** Drop the memoized rates (tests, and a manual refresh). */
+export function clearRateCache() { cache.clear(); }
+
+export default { usdRate, syncRate, convert, parseRate, normalizeCurrency, envRate, clearRateCache, SUPPORTED_CURRENCIES };