@axplusb/kepler 1.0.9 → 2.0.0

package/src/ui/spinner.mjs

@@ -0,0 +1,116 @@
+/**
+ * Single shared spinner — Mission Control (PRD-055 §4.4).
+ *
+ * One spinner instance per process. The repl and status bar consume frames
+ * from the same source so the eye never sees two animations out of phase.
+ *
+ * Usage:
+ *
+ *   const stop = startSpinner('Reading auth.py');
+ *   await doWork();
+ *   stop();                          // clears the line and stops the timer
+ *
+ * Or, for a managed line that already exists (e.g. the status bar):
+ *
+ *   const tick = spinnerFrame();     // current frame, advances on next call
+ *
+ * Behavior:
+ *   - 120ms per frame.
+ *   - Suppressed entirely when stdout is not a TTY or when KEPLER_PLAIN=1.
+ *     The `start`/`stop` API is still safe to call (no-op).
+ *   - Color follows the current orbit (orchestrated by the caller via the
+ *     palette token). Default: brand.primary.
+ *   - ASCII fallback (when no Unicode): 'plain dot rotation'.
+ */
+
+import { paint } from './palette.mjs';
+import { term } from './term.mjs';
+
+// 8-step rotation. The PRD spec calls for ◯ → ◔ → ◑ → ◕ → ● → ◕ → ◑ → ◔
+// which yields a perceptual "breathing" cycle rather than a left-right spin.
+const FRAMES_UTF = ['◯', '◔', '◑', '◕', '●', '◕', '◑', '◔'];
+const FRAMES_ASCII = ['.', 'o', 'O', '@', 'O', 'o', '.', ' '];
+
+const INTERVAL_MS = 120;
+
+let _frame = 0;
+
+/**
+ * Current spinner glyph. Advances the cursor each call.
+ * Honors capability detection automatically.
+ */
+export function spinnerFrame(painter = paint.brand.primary) {
+  const frames = term().unicode ? FRAMES_UTF : FRAMES_ASCII;
+  const ch = frames[_frame % frames.length];
+  _frame = (_frame + 1) % frames.length;
+  return painter ? painter(ch) : ch;
+}
+
+/**
+ * Reset to frame 0 — useful at the start of a new turn so consecutive
+ * tool calls do not inherit each other's phase.
+ */
+export function resetSpinner() {
+  _frame = 0;
+}
+
+/**
+ * Start an inline spinner attached to `text`. Returns a stop function.
+ *
+ * The line is re-rendered in place using carriage return + erase, so the
+ * caller does not need to manage cursor state. If the terminal cannot
+ * render in place (non-TTY, dumb terminal, plain mode), the spinner becomes
+ * a single static line `"… text"` written once.
+ */
+export function startSpinner(text, { stream = process.stderr, painter, color = 'brand.primary' } = {}) {
+  const t = term();
+  if (!t.isTTY || t.plain || !t.color) {
+    try { stream.write(`… ${text}\n`); } catch {}
+    return () => {};
+  }
+
+  const paintFn = painter || tokenPainter(color);
+  let stopped = false;
+
+  const render = () => {
+    if (stopped) return;
+    const glyph = spinnerFrame(paintFn);
+    try {
+      stream.write(`\r\x1b[2K${glyph} ${paint.text.dim(text)}`);
+    } catch {
+      // Stream closed mid-spin — stop quietly.
+      stop();
+    }
+  };
+
+  render();
+  const handle = setInterval(render, INTERVAL_MS);
+
+  function stop() {
+    if (stopped) return;
+    stopped = true;
+    clearInterval(handle);
+    try {
+      stream.write('\r\x1b[2K');
+    } catch {}
+  }
+
+  return stop;
+}
+
+/**
+ * Look up a painter function from a dotted token name (e.g. 'brand.accent').
+ * Falls back to the identity painter when the token does not exist.
+ */
+function tokenPainter(tokenPath) {
+  const [ns, name] = String(tokenPath || '').split('.');
+  const group = paint[ns];
+  if (group && typeof group[name] === 'function') return group[name];
+  return (s) => String(s ?? '');
+}
+
+/**
+ * Interval used by the shared spinner. Exposed for the status bar to
+ * synchronize its own re-paints with the spinner phase.
+ */
+export const SPINNER_INTERVAL_MS = INTERVAL_MS;

package/src/ui/status-bar.mjs

@@ -0,0 +1,275 @@
+/**
+ * Persistent two-line status bar — Mission Control (PRD-055 §5).
+ *
+ * Anchors itself to the bottom two rows of the terminal using a DECSTBM
+ * scroll region:
+ *
+ *   ┌────────────────────────────────────────────────┐
+ *   │  scroll region (rows 1..rows-2)                │
+ *   │  scroll region (rows 1..rows-2)                │
+ *   │  scroll region (rows 1..rows-2)                │
+ *   ├────────────────────────────────────────────────┤
+ *   │  status line 1 — ORBIT | TASK | TURN | COST    │
+ *   │  status line 2 — keyboard dock                  │
+ *   └────────────────────────────────────────────────┘
+ *
+ * The scroll region is set once at mount; afterwards normal stdout/stderr
+ * writes scroll within the upper region without ever touching the bar.
+ *
+ * Behavior:
+ *   - No-op when stdout is not a TTY, or when KEPLER_PLAIN=1.
+ *     The `mount/unmount/setOrbit` API is still safe to call.
+ *   - Re-renders on state change (event-driven), not on a timer (except
+ *     while in a state with a live spinner — see `_tickIfNeeded`).
+ *   - SIGWINCH handler re-pads and re-sets the scroll region.
+ *   - `unmount()` MUST be called before exit so the scroll region is
+ *     restored and the cursor is shown.
+ *
+ * Implementation notes:
+ *   - All output goes to stderr to keep stdout pipe-clean for `--print`/
+ *     headless modes; if stdout is the only thing piped, the headless
+ *     branch already short-circuits this module before any escape codes
+ *     are emitted.
+ *   - The PRD's "tput sc/rc" hint is shorthand. We use the actual VT100
+ *     scroll region (`CSI top;bot r`) plus save/restore cursor.
+ */
+
+import { paint, width as visibleWidth } from './palette.mjs';
+import { icons } from './icons.mjs';
+import { spinnerFrame, SPINNER_INTERVAL_MS } from './spinner.mjs';
+import { term, onResize } from './term.mjs';
+import { ORBITS } from '../state/orbit.mjs';
+import { dockForOrbit, renderDock } from './dock.mjs';
+
+const ESC = '\x1b[';
+const OUT = process.stderr;
+
+// ── Orbit metadata: visual style + label ─────────────────────────────────
+
+const ORBIT_META = {
+  [ORBITS.IDLE]:      { label: 'IDLE',      paint: (s) => paint.text.dim(s),    spinning: false },
+  [ORBITS.DISCOVERY]: { label: 'DISCOVERY', paint: (s) => paint.text.dim(s),    spinning: true  },
+  [ORBITS.PLANNING]:  { label: 'PLANNING',  paint: (s) => paint.state.warn(s),  spinning: true  },
+  [ORBITS.EXECUTION]: { label: 'EXECUTION', paint: (s) => paint.brand.primary(s), spinning: true },
+  [ORBITS.ALIGNMENT]: { label: 'ALIGNMENT', paint: (s) => paint.brand.data(s),  spinning: true  },
+  [ORBITS.AWAITING]:  { label: 'AWAITING',  paint: (s) => paint.brand.accent(s), spinning: false, border: true },
+  [ORBITS.PAUSED]:    { label: 'PAUSED',    paint: (s) => paint.state.warn(s),  spinning: false },
+};
+
+// ── State held by the singleton ──────────────────────────────────────────
+
+let mounted = false;
+let unsubResize = null;
+let tickInterval = null;
+let lastSnapshot = null;
+let resetting = false;
+
+// ── Low-level cursor / region helpers ────────────────────────────────────
+
+function write(s) { try { OUT.write(s); } catch {} }
+
+function setScrollRegion(top, bottom) { write(`${ESC}${top};${bottom}r`); }
+function clearScrollRegion()           { write(`${ESC}r`); }
+function saveCursor()                  { write(`${ESC}s`); }
+function restoreCursor()               { write(`${ESC}u`); }
+function moveTo(row, col)              { write(`${ESC}${row};${col}H`); }
+function clearLine()                   { write(`${ESC}2K`); }
+function hideCursor()                  { write(`${ESC}?25l`); }
+function showCursor()                  { write(`${ESC}?25h`); }
+
+// ── Layout: assemble the two lines ───────────────────────────────────────
+
+function formatCost(usd) {
+  if (typeof usd !== 'number' || !Number.isFinite(usd)) return '$0.00';
+  if (usd < 0.01) return `$${usd.toFixed(4)}`;
+  return `$${usd.toFixed(2)}`;
+}
+
+function buildLineOne(snap, cols) {
+  const meta = ORBIT_META[snap.orbit] || ORBIT_META[ORBITS.IDLE];
+  const sep  = paint.text.dim(' │ ');
+
+  const glyph = meta.spinning ? spinnerFrame(meta.paint) : meta.paint(icons.orbit);
+  const orbitLabel = `${glyph} ${meta.paint('ORBIT: ' + meta.label)}`;
+
+  const segments = [orbitLabel];
+
+  if (snap.task) {
+    segments.push(paint.text.dim('TASK: ') + paint.text.primary(snap.task));
+  }
+  if (snap.subAgents > 0) {
+    const noun = snap.subAgents === 1 ? 'sub-agent' : 'sub-agents';
+    segments.push(paint.brand.data(`${icons.subAgent} ${snap.subAgents} ${noun}`) + ' ' + paint.text.dim('active'));
+  }
+  if (snap.turn > 0) {
+    const turnText = snap.maxTurn > 0 ? `TURN ${snap.turn}/${snap.maxTurn}` : `TURN ${snap.turn}`;
+    segments.push(paint.text.dim(turnText));
+  }
+  segments.push(paint.text.dim('COST ') + paint.brand.data(formatCost(snap.cost)));
+
+  return assembleLine(segments, sep, cols);
+}
+
+function buildLineTwo(snap, cols) {
+  if (snap.orbit === ORBITS.AWAITING && snap.awaitingTool) {
+    const prefix = paint.brand.accent(`${icons.warn} APPROVAL  `) + paint.text.primary(snap.awaitingTool);
+    const tail = renderDock(dockForOrbit(snap.orbit), Math.max(0, cols - visibleWidth(prefix) - 2));
+    return ` ${prefix}  ${tail}`;
+  }
+  const hints = dockForOrbit(snap.orbit);
+  return ' ' + renderDock(hints, cols - 1);
+}
+
+/**
+ * Concatenate segments with separators, dropping trailing segments when
+ * they exceed `cols` of visible width. Always keeps the first segment.
+ */
+function assembleLine(segments, sep, cols) {
+  if (segments.length === 0) return '';
+  let out = ' ' + segments[0];
+  let used = 1 + visibleWidth(segments[0]);
+  for (let i = 1; i < segments.length; i++) {
+    const piece = sep + segments[i];
+    const cost = visibleWidth(piece);
+    if (used + cost > cols) break;
+    out += piece;
+    used += cost;
+  }
+  return out;
+}
+
+// ── Render ───────────────────────────────────────────────────────────────
+
+function paintLine(text, cols) {
+  const pad = Math.max(0, cols - visibleWidth(text));
+  return text + ' '.repeat(pad);
+}
+
+function render(snap) {
+  if (!mounted || !snap) return;
+  const t = term();
+  if (!t.isTTY || t.plain) return;
+
+  const cols = Math.max(20, t.columns);
+  const rows = Math.max(4,  t.rows);
+
+  const line1 = paintLine(buildLineOne(snap, cols), cols);
+  const line2 = paintLine(buildLineTwo(snap, cols), cols);
+
+  saveCursor();
+  moveTo(rows - 1, 1);
+  clearLine();
+  write(line1);
+  moveTo(rows, 1);
+  clearLine();
+  write(line2);
+  restoreCursor();
+}
+
+// ── Public API ───────────────────────────────────────────────────────────
+
+/**
+ * Mount the status bar. Sets up the scroll region, hides the cursor, and
+ * registers SIGWINCH. Returns `false` when the environment is not TTY
+ * (caller can short-circuit).
+ *
+ * Safe to call multiple times — re-entrant calls are no-ops.
+ */
+export function mount() {
+  if (mounted) return true;
+  const t = term();
+  if (!t.isTTY || t.plain) return false;
+
+  // Reserve the bottom 2 rows.
+  const rows = Math.max(4, t.rows);
+  setScrollRegion(1, rows - 2);
+  moveTo(rows - 1, 1); clearLine();
+  moveTo(rows, 1);     clearLine();
+  // Restore cursor into the scroll region so subsequent writes go there.
+  moveTo(rows - 2, 1);
+
+  unsubResize = onResize(() => {
+    if (!mounted) return;
+    const r = Math.max(4, term().rows);
+    setScrollRegion(1, r - 2);
+    if (lastSnapshot) render(lastSnapshot);
+  });
+
+  // Cleanup hooks — exits, signals, uncaught crash all restore the terminal.
+  process.once('exit',    safeUnmount);
+  process.once('SIGINT',  () => { safeUnmount(); process.exit(130); });
+  process.once('SIGTERM', () => { safeUnmount(); process.exit(143); });
+
+  mounted = true;
+  return true;
+}
+
+/**
+ * Tear down: restore scroll region, show cursor. Must be called before
+ * process exit. Safe to call when not mounted.
+ */
+export function unmount() {
+  if (!mounted || resetting) return;
+  resetting = true;
+  try {
+    clearScrollRegion();
+    showCursor();
+    if (unsubResize) { unsubResize(); unsubResize = null; }
+    if (tickInterval) { clearInterval(tickInterval); tickInterval = null; }
+  } finally {
+    mounted = false;
+    resetting = false;
+  }
+}
+
+function safeUnmount() { try { unmount(); } catch {} }
+
+/**
+ * Push a new orbit snapshot. Triggers a render and starts/stops the
+ * spinner tick as needed.
+ */
+export function setOrbit(snap) {
+  lastSnapshot = snap;
+  if (!mounted) return;
+  const meta = ORBIT_META[snap.orbit] || ORBIT_META[ORBITS.IDLE];
+  if (meta.spinning) startTick();
+  else stopTick();
+  render(snap);
+}
+
+/** Force an immediate redraw using the last known snapshot. */
+export function redraw() {
+  if (lastSnapshot) render(lastSnapshot);
+}
+
+function startTick() {
+  if (tickInterval || !mounted) return;
+  tickInterval = setInterval(() => {
+    if (!mounted || !lastSnapshot) return;
+    render(lastSnapshot);
+  }, SPINNER_INTERVAL_MS);
+  if (typeof tickInterval.unref === 'function') tickInterval.unref();
+}
+
+function stopTick() {
+  if (!tickInterval) return;
+  clearInterval(tickInterval);
+  tickInterval = null;
+}
+
+/**
+ * Connect an `orbit` state machine instance to this status bar. Returns an
+ * unsubscribe function. The bar is mounted automatically; tear it down with
+ * `unmount()` or by calling the returned function (which also unmounts).
+ */
+export function attachOrbit(orbit) {
+  if (!orbit || typeof orbit.on !== 'function') return () => {};
+  if (!mount()) return () => {}; // non-TTY: silently ignore
+  const unsub = orbit.on('change', setOrbit);
+  // Initial paint
+  setOrbit(orbit.state());
+  return () => {
+    try { unsub(); } catch {}
+    unmount();
+  };
+}

package/src/ui/sub-agent.mjs

@@ -0,0 +1,152 @@
+/**
+ * Sub-agent block renderer — Mission Control (PRD-055 §7).
+ *
+ * Renders the open/close pair for a sub-agent block, dimmed throughout so
+ * the primary agent reads bright by contrast. Inner tool cards are indented
+ * via the `subAgentIndent()` helper so they nest visually under the header.
+ *
+ *   🛰️ explore "JWT lifecycle"  ▸ running (deepseek/deepseek-v4-flash)
+ *        🔭 Search code "expire"        → 6 matches
+ *        🔭 Read file auth.py L120-180   → 60 lines
+ *        └ ✅ returned 3 files identified · $0.004 · 2.1s
+ *
+ * Maintains a depth stack so concurrent / nested sub-agents indent further
+ * and so callers can ask `inSubAgent()` / `depth()` without threading state.
+ *
+ * No I/O — caller writes the returned strings to stderr. This keeps the
+ * module testable from a plain Node script.
+ */
+
+import { paint } from './palette.mjs';
+import { icons } from './icons.mjs';
+
+const SUB_ICONS = {
+  explore: '🔭',
+  plan:    '📐',
+  verify:  '✅',
+  debug:   '🪲',
+  refactor:'♻️',
+};
+
+// ── Active stack ─────────────────────────────────────────────────────────
+
+const _stack = []; // [{ id, type, startedAt }]
+
+/** How many sub-agents are currently open. */
+export function depth() { return _stack.length; }
+export function inSubAgent() { return _stack.length > 0; }
+
+/**
+ * Indent string for a tool card line nested under N sub-agents.
+ * 5 cols per level matches the existing `'     '` legacy indent.
+ */
+export function subAgentIndent(extraDepth = 0) {
+  const d = _stack.length + extraDepth;
+  if (d <= 0) return '  ';
+  return ' '.repeat(2 + d * 3);
+}
+
+// ── Render ───────────────────────────────────────────────────────────────
+
+/**
+ * Open a sub-agent block. Pushes onto the stack; returns the lines to print.
+ *
+ * @returns {string} ANSI-styled multi-line block (no trailing newline).
+ */
+export function renderSubAgentOpen({ id, type, model, query, parentDepth } = {}) {
+  const t = type || 'sub-agent';
+  const depthBefore = _stack.length;
+  _stack.push({ id: id || `${t}-${depthBefore}-${tag()}`, type: t, startedAt: Date.now() });
+
+  const indent = ' '.repeat(2 + depthBefore * 3);
+  const iconChar = SUB_ICONS[t] || icons.subAgent;
+  const head = `${indent}${iconChar} ${paint.brand.data(t)} ${paint.text.dim(`"${truncate(query || '', 60)}"`)}`;
+  const tag1 = paint.text.dim(`▸ running${model ? ` (${model})` : ''}`);
+
+  return query
+    ? `\n${head}  ${tag1}`
+    : `\n${indent}${iconChar} ${paint.brand.data(t)}  ${tag1}`;
+}
+
+/**
+ * Close the most recent sub-agent block. Pops the stack; returns the close
+ * line with optional cost / token / duration attribution per PRD §7.3.
+ *
+ *   └ ✅ returned 3 files identified · 1.2k tok · $0.004 · 2.1s
+ *   └ ✗ explore agent failed
+ *
+ * Caller passes `success` (default true), `summary` ("returned N files"),
+ * and any of `{ costUsd, tokens, durationS, toolCalls, iterations }`.
+ */
+export function renderSubAgentClose({
+  type,
+  success = true,
+  summary = '',
+  costUsd,
+  tokens,
+  durationS,
+  toolCalls,
+  iterations,
+  error,
+} = {}) {
+  // Match-pop: if the type doesn't match the top of stack we still pop the
+  // top entry — backends never emit interleaved open/close, so this is the
+  // safe behavior.
+  const opened = _stack.pop();
+  const t = type || opened?.type || 'sub-agent';
+  const indent = ' '.repeat(2 + _stack.length * 3);
+
+  if (!success) {
+    const line = `${indent}${paint.text.dim('└')} ${paint.state.danger('✗')} ${paint.text.dim(`${t} agent failed`)}`;
+    if (error) {
+      return `${line}\n${indent}    ${paint.state.danger(truncate(error, 140))}`;
+    }
+    return line;
+  }
+
+  const parts = [];
+  if (toolCalls > 0)              parts.push(`${toolCalls} tools`);
+  if (iterations > 0)             parts.push(`${iterations} iter`);
+  if (tokens > 0)                 parts.push(`${formatTokens(tokens)} tok`);
+  if (typeof costUsd === 'number' && costUsd > 0) parts.push(formatCost(costUsd));
+  if (durationS != null)          parts.push(`${Number(durationS).toFixed(1)}s`);
+  const detail = parts.length ? paint.text.dim(' · ' + parts.join(' · ')) : '';
+
+  const body = summary
+    ? paint.text.dim(summary)
+    : paint.text.dim(`${t} returned`);
+
+  return `${indent}${paint.text.dim('└')} ${paint.state.success('✅')} ${body}${detail}`;
+}
+
+/**
+ * Force-clear the stack. Use after a `complete` event or when cancelling so
+ * a stale entry doesn't keep indenting future output.
+ */
+export function resetSubAgents() { _stack.length = 0; }
+
+// ── helpers ──────────────────────────────────────────────────────────────
+
+function truncate(text, n) {
+  const s = String(text || '');
+  return s.length <= n ? s : s.slice(0, n - 1) + '…';
+}
+
+function formatTokens(n) {
+  if (!Number.isFinite(n)) return '0';
+  if (n >= 1000) return `${(n / 1000).toFixed(1)}k`;
+  return String(Math.round(n));
+}
+
+function formatCost(usd) {
+  if (usd < 0.001) return `$${usd.toFixed(5)}`;
+  if (usd < 0.01)  return `$${usd.toFixed(4)}`;
+  return `$${usd.toFixed(3)}`;
+}
+
+function tag() {
+  // Avoid Date.now()/Math.random() drift across re-renders — depth+counter is
+  // enough to keep ids unique within a process.
+  tag._n = (tag._n || 0) + 1;
+  return tag._n.toString(36);
+}

package/src/ui/term.mjs

@@ -0,0 +1,159 @@
+/**
+ * Terminal capability detection.
+ *
+ * Resolves once at import. Re-evaluation requires `refresh()` (used by tests
+ * and the rare command that toggles a relevant env var mid-process).
+ *
+ * Capability tiers (highest first):
+ *   truecolor - 24-bit RGB (e.g. iTerm2, modern xterm, Windows Terminal)
+ *   ansi256  - 256-color palette
+ *   ansi16   - basic 16 colors
+ *   none     - no color (NO_COLOR=1, dumb terminal, non-TTY without override)
+ */
+
+const TRUECOLOR_TERMS = new Set([
+  'truecolor',
+  '24bit',
+  '24-bit',
+]);
+
+const ANSI256_TERMS = [
+  /-256(color)?$/i,
+  /^xterm/i,
+  /^screen/i,
+  /^tmux/i,
+  /^rxvt-unicode/i,
+  /^alacritty/i,
+];
+
+const DUMB_TERMS = new Set(['', 'dumb', 'unknown']);
+
+function readEnv() {
+  const env = process.env || {};
+  return {
+    NO_COLOR: env.NO_COLOR,
+    FORCE_COLOR: env.FORCE_COLOR,
+    KEPLER_PLAIN: env.KEPLER_PLAIN,
+    COLORTERM: (env.COLORTERM || '').toLowerCase(),
+    TERM: (env.TERM || '').toLowerCase(),
+    TERM_PROGRAM: env.TERM_PROGRAM || '',
+    CI: env.CI,
+  };
+}
+
+function detectColorLevel(env, isTTY) {
+  // Hard opt-out (https://no-color.org). Honored even on TTYs.
+  if (env.NO_COLOR !== undefined && env.NO_COLOR !== '') return 'none';
+  if (env.KEPLER_PLAIN === '1') return 'none';
+
+  // Hard opt-in. FORCE_COLOR=1|2|3 maps to ansi16|ansi256|truecolor.
+  // FORCE_COLOR with no value or =true falls through to detection.
+  if (env.FORCE_COLOR !== undefined) {
+    const v = String(env.FORCE_COLOR).trim();
+    if (v === '0' || v === 'false') return 'none';
+    if (v === '1') return 'ansi16';
+    if (v === '2') return 'ansi256';
+    if (v === '3') return 'truecolor';
+    // Any other truthy value: continue detection but allow non-TTY.
+    isTTY = true;
+  }
+
+  // No TTY and not forced: no color.
+  if (!isTTY) return 'none';
+
+  if (DUMB_TERMS.has(env.TERM)) return 'none';
+
+  if (TRUECOLOR_TERMS.has(env.COLORTERM)) return 'truecolor';
+
+  // Some terminal emulators advertise truecolor through TERM_PROGRAM.
+  if (env.TERM_PROGRAM === 'iTerm.app' || env.TERM_PROGRAM === 'WezTerm') {
+    return 'truecolor';
+  }
+  if (env.TERM_PROGRAM === 'vscode' || env.TERM_PROGRAM === 'Apple_Terminal') {
+    return 'ansi256';
+  }
+
+  if (ANSI256_TERMS.some(re => re.test(env.TERM))) return 'ansi256';
+
+  return 'ansi16';
+}
+
+function detectUnicode(env) {
+  if (env.KEPLER_PLAIN === '1') return false;
+  // Most modern terminals on macOS/Linux handle UTF-8.
+  // Windows ConEmu / older terminals are the main holdouts; conservative
+  // fallback when LANG and LC_* are missing or explicitly POSIX.
+  const lang = (process.env.LANG || process.env.LC_ALL || process.env.LC_CTYPE || '').toLowerCase();
+  if (!lang) return process.platform !== 'win32';
+  if (lang.includes('utf')) return true;
+  return false;
+}
+
+function compute() {
+  const env = readEnv();
+  const isTTY = !!(process.stdout && process.stdout.isTTY);
+  const level = detectColorLevel(env, isTTY);
+  return {
+    isTTY,
+    colorLevel: level,                       // 'none' | 'ansi16' | 'ansi256' | 'truecolor'
+    color: level !== 'none',
+    truecolor: level === 'truecolor',
+    ansi256: level === 'ansi256' || level === 'truecolor',
+    unicode: detectUnicode(env),
+    plain: env.KEPLER_PLAIN === '1',
+    columns: (process.stdout && process.stdout.columns) || 80,
+    rows: (process.stdout && process.stdout.rows) || 24,
+    ci: !!env.CI,
+  };
+}
+
+let _capabilities = compute();
+
+/**
+ * Current terminal capabilities. Stable until `refresh()` is called.
+ */
+export function term() {
+  return _capabilities;
+}
+
+/**
+ * Re-run capability detection. Tests, `/config` reloads, or runtime env changes.
+ */
+export function refresh() {
+  _capabilities = compute();
+  return _capabilities;
+}
+
+/**
+ * Listen for terminal resizes. Returns an unsubscribe function.
+ * Callers receive the latest capabilities object (with updated columns/rows).
+ */
+export function onResize(handler) {
+  if (typeof handler !== 'function') return () => {};
+  const stream = process.stdout;
+  if (!stream || typeof stream.on !== 'function') return () => {};
+
+  const onChange = () => {
+    _capabilities = {
+      ..._capabilities,
+      columns: stream.columns || _capabilities.columns,
+      rows: stream.rows || _capabilities.rows,
+    };
+    handler(_capabilities);
+  };
+  stream.on('resize', onChange);
+  return () => stream.off('resize', onChange);
+}
+
+/**
+ * Force a capability level. Test-only escape hatch.
+ * Pass `null` to clear and re-detect.
+ */
+export function _setForTesting(overrides) {
+  if (overrides === null) {
+    _capabilities = compute();
+    return _capabilities;
+  }
+  _capabilities = { ..._capabilities, ...overrides };
+  return _capabilities;
+}