@causyne/agent 0.0.0-stage → 1.10.0

package/src/tui/statusLine.js

@@ -0,0 +1,254 @@
+// The line that tells the user what is happening to their money and their time.
+//
+// While a turn ran, the chat printed one thing:
+//
+//   ⠋ Thinking…
+//
+// and that was the entire signal for what could be a four-minute, forty-step,
+// several-dollar run. The user could not see elapsed time, which model was
+// spending, how many steps had gone by, how many tokens the turn had burned, or
+
+// those numbers was already in memory — the loop broadcasts `usage_update` on
+// every response and the config carries the model — and none of it was shown.
+//
+// openclaw puts elapsed and connection state on its waiting line; opencode keeps
+// a permanent footer with cwd, LSP and MCP counts. This is the same idea in
+// Causyne's register: no whimsy, just the four numbers a person needs to decide
+// whether to let a run continue or press esc.
+//
+// The line degrades by DROPPING SEGMENTS, right to left, until it fits. A narrow
+// terminal loses the cost before it loses the elapsed time, and loses the
+// elapsed time before it loses the message. It never wraps, because a wrapping
+// spinner leaves debris every tick.
+//
+// Pure Node over ./theme.js and ./text.js. No dependency, no shell.
+
+import { paint, dim, GLYPHS } from './theme.js';
+import { truncate, visibleWidth, safeDisplay, shortenHome } from './text.js';
+import { contextMeter } from './block.js';
+import { CHARS_PER_TOKEN } from '../contextManager.js';
+
+/** 1234 -> "1.2k", 1234567 -> "1.2M". Token counts are read, not summed. */
+export function compactCount(value) {
+  const n = Number(value) || 0;
+  if (n < 1000) return String(Math.round(n));
+  if (n < 1000000) return `${(n / 1000).toFixed(n < 10000 ? 1 : 0)}k`;
+  return `${(n / 1000000).toFixed(1)}M`;
+}
+
+/**
+ * Money, at the precision the number deserves.
+ *
+ * Sub-cent runs printed as "$0.00" read as free, which is how a user learns not
+ * to look at the cost at all.
+ */
+export function formatCost(value) {
+  const n = Number(value) || 0;
+  if (n <= 0) return '$0';
+  if (n < 0.01) return `$${n.toFixed(4)}`;
+  if (n < 1) return `$${n.toFixed(3)}`;
+  return `$${n.toFixed(2)}`;
+}
+
+export function formatElapsed(ms) {
+  const total = Math.max(0, Math.round(ms / 1000));
+  if (total < 60) return `${(ms / 1000).toFixed(1)}s`;
+  const minutes = Math.floor(total / 60);
+  const seconds = total % 60;
+  if (minutes < 60) return `${minutes}m${String(seconds).padStart(2, '0')}s`;
+  return `${Math.floor(minutes / 60)}h${String(minutes % 60).padStart(2, '0')}m`;
+}
+
+/** Strip a provider prefix so "anthropic/claude-opus-5" reads as the model. */
+function shortModel(model) {
+  const name = String(model || '').split('/').pop() || '';
+  return name.length > 22 ? name.slice(0, 21) + GLYPHS.ellipsis : name;
+}
+
+export class StatusLine {
+  constructor() {
+    this.model = '';
+    this.provider = '';
+    this.tier = '';
+    this.cwd = '';
+    // Both in CHARACTERS — the unit the window is actually budgeted in.
+    // `contextLimit` always was; the numerator was the thing that was wrong.
+    this.contextLimit = 0;
+    this.contextChars = 0;
+    this.reset();
+  }
+
+  /** Session-lifetime facts, set once from the same info as the header. */
+  setSession(info = {}) {
+    this.model = shortModel(info.model);
+    this.provider = info.provider ? String(info.provider) : '';
+    this.tier = info.tier ? String(info.tier) : '';
+    // The idle footer answers "where am I and how much room is left", which is
+    // what opencode's permanent footer shows (cwd left, context right). Neither
+    // fact was reachable once the session header had scrolled away.
+    this.cwd = info.cwd ? String(info.cwd) : '';
+    this.contextLimit = Number(info.contextLimit) || 0;
+    return this;
+  }
+
+  /** Per-turn counters. */
+  reset() {
+    this.turnTokens = 0;
+    this.turnCost = 0;
+    this.cachedTokens = 0;
+    this.contextChars = 0;
+    return this;
+  }
+
+  /**
+   * The idle footer: where you are, and how much context is left.
+   *
+   * A separate shape from the working line on purpose. While a turn runs the
+   * user is deciding whether to let it continue, so the line carries elapsed,
+   * steps, tokens and cost. Between turns none of those are actionable, and the
+   * two facts that are — the working directory and the remaining context — had
+   * nowhere to live. Same justification as render(): left fact, right numbers.
+   */
+  renderIdle({ width = 80, hint = '' } = {}) {
+    const budget = Math.max(10, width - 1);
+    // Characters in, characters out — then one conversion, so both halves of
+    // "24K (20%)" describe the same measurement. Feeding this the task's
+    // CUMULATIVE token spend and dividing by a character pool is what produced
+    // a permanent "290K (99%)" on a window that was nowhere near full.
+    const meter = contextMeter(
+      Math.round(this.contextChars / CHARS_PER_TOKEN),
+      Math.round(this.contextLimit / CHARS_PER_TOKEN)
+    );
+    const segments = [];
+    if (meter) segments.push(meter);
+    if (hint) segments.push(hint);
+
+    const separator = `  ${GLYPHS.dot}  `;
+    let kept = segments.slice();
+    let tail = kept.join(separator);
+    // Drop the hint before the number: a truncated keybinding is a wrong one.
+    while (kept.length > 1 && visibleWidth(tail) > Math.floor(budget / 2)) {
+      kept.pop();
+      tail = kept.join(separator);
+    }
+    if (visibleWidth(tail) > budget) tail = '';
+
+    const room = tail ? Math.max(0, budget - visibleWidth(tail) - visibleWidth(separator)) : budget;
+    const where = this.cwd ? truncate(shortenHome(this.cwd), room, GLYPHS.ellipsis) : '';
+    const left = dim(where);
+    if (!tail) return left;
+
+    const gap = Math.max(
+      visibleWidth(separator),
+      width - 1 - visibleWidth(left) - visibleWidth(tail)
+    );
+    return `${left}${' '.repeat(gap)}${dim(tail)}`;
+  }
+
+  /**
+   * Consume a `usage_update` frame.
+   *
+   * taskCostUsd is the whole task; costUsd is this response. The turn total is
+   * what the user is deciding about right now, so accumulate that.
+   */
+  onUsage(msg = {}) {
+    // TASK scope, explicitly. `usedTokens` now carries the DAILY total, which is
+    
+    // shows — the working line is about the turn the user is deciding on.
+    this.turnTokens = Number(msg.taskTokens) || Number(msg.usedTokens) || this.turnTokens;
+    // What the request actually carried, measured at the point it was built.
+    if (Number(msg.contextChars) > 0) this.contextChars = Number(msg.contextChars);
+    if (Number(msg.contextLimitChars) > 0) this.contextLimit = Number(msg.contextLimitChars);
+    const responseCost = Number(msg.costUsd) || 0;
+    const taskCost = Number(msg.taskCostUsd) || 0;
+    // Prefer the task total when the provider reports one — it already includes
+    // every response, and summing on top would double-count.
+    this.turnCost = taskCost > 0 ? taskCost : this.turnCost + responseCost;
+    this.cachedTokens = Number(msg.cachedTokens) || 0;
+    return this;
+  }
+
+  /**
+   * Build the line.
+   *
+   * `segments` are ordered most to least important. Anything that does not fit
+   * is dropped whole — never truncated into a misleading half-number.
+   */
+  render({ message = '', elapsedMs = 0, steps = 0, width = 80, spinnerFrame = '' } = {}) {
+    const head = spinnerFrame ? `${paint('accent', spinnerFrame)} ` : '';
+    const budget = Math.max(10, width - visibleWidth(head) - 1);
+
+    const segments = [];
+    if (elapsedMs > 0) segments.push(formatElapsed(elapsedMs));
+    if (steps > 0) segments.push(`step ${steps}`);
+    if (this.turnTokens > 0) segments.push(`${compactCount(this.turnTokens)} tok`);
+    if (this.turnCost > 0) segments.push(formatCost(this.turnCost));
+    if (this.cachedTokens > 0) segments.push(`${compactCount(this.cachedTokens)} cached`);
+    if (this.model) segments.push(this.model);
+
+    const separator = `  ${GLYPHS.dot}  `;
+    const text = safeDisplay(message);
+
+    // Drop segments from the right until the message fits at its natural width.
+    //
+    // The message is what the user is reading; the numbers are what they glance
+    // at. Reserving space for the message FIRST is what stops a wide terminal
+    // from printing "reading project fi…" next to six perfectly intact counters.
+    // The reservation is capped at half the line so a very long status cannot
+    // squeeze every number out.
+    let kept = segments.slice();
+    const wanted = Math.min(visibleWidth(text), Math.max(18, Math.floor(budget / 2)));
+    while (kept.length > 0) {
+      const tail = kept.join(separator);
+      if (visibleWidth(tail) + separator.length + wanted <= budget) break;
+      kept.pop();
+    }
+
+    const tail = kept.length > 0 ? kept.join(separator) : '';
+    const messageBudget = tail
+      ? Math.max(1, budget - visibleWidth(tail) - separator.length)
+      : budget;
+    const body = truncate(text, messageBudget, GLYPHS.ellipsis);
+
+    const left = `${head}${paint('muted', body)}`;
+    if (!tail) return left;
+
+    // Justify: message left, numbers hard right.
+    //
+    // Packing everything against the left edge wastes the whole right half of a
+    // wide terminal and makes the counters drift horizontally as the status text
+    // changes length — the eye has to re-find them every frame. Pinning them to
+    // the right edge means they sit in the same column all session. This is the
+    // shape opencode's session footer uses (justifyContent="space-between", the
+    // directory left and the counters right).
+    //
+    // The fitting loop above already guarantees room for a separator between the
+    // two, so the gap can never collapse to nothing.
+    // Justify against width - 1, not width.
+    //
+    // The fitting loop above budgets `width - head - 1`, but this gap was
+    // computed against the full `width`, so the finished line came back exactly
+    // `width` columns — flush against the right edge, with no slack at all. A
+    // terminal that renders one of the ambiguous-width glyphs in this line (`·`
+    // appears twice) as two columns then wraps it, and a wrapped row in the live
+    // region corrupts erase()'s row accounting. One reserved column removes the
+    // whole class of failure at its source; ChatPrompt.clampRows() is the net.
+    const gap = Math.max(
+      visibleWidth(separator),
+      width - 1 - visibleWidth(left) - visibleWidth(tail)
+    );
+    return `${left}${' '.repeat(gap)}${dim(tail)}`;
+  }
+
+  /**
+   * The non-TTY form: no spinner, no elapsed clock, printed once.
+   *
+   * Piped into a CI log an animated line becomes thousands of junk rows, and an
+   * elapsed time that never updates is worse than none.
+   */
+  renderStatic(message, width = 80) {
+    const parts = [safeDisplay(message)];
+    if (this.model) parts.push(this.model);
+    return truncate(`${GLYPHS.dot} ${parts.join(`  ${GLYPHS.dot}  `)}`, width, GLYPHS.ellipsis);
+  }
+}

package/src/tui/text.js

@@ -0,0 +1,345 @@
+// ANSI-aware text primitives.
+//
+// Every one of these exists because the CLI got a terminal detail wrong:
+//
+//  * `padEnd` on a coloured string pads by BYTE length, so escape sequences
+//    counted toward the column and every aligned table drifted.
+//  * `slice()` on a coloured string can cut through the middle of an escape,
+//    leaking `[38;2;96;205` as literal text and leaving the colour stuck on.
+//  * Tool output was printed raw — see sanitize() below, which is a security
+//    fix, not a cosmetic one.
+//
+// Pure JS. No dependency, no shell.
+
+import os from 'os';
+
+// CSI sequences (colour, cursor movement, erase) and OSC sequences (window
+// title, hyperlinks — terminated by BEL or ST).
+const CSI_PATTERN = /\x1b\[[0-?]*[ -/]*[@-~]/g;
+const OSC_PATTERN = /\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g;
+const OTHER_ESCAPE_PATTERN = /\x1b[@-Z\\-_]/g;
+
+/** Everything that is an escape sequence rather than visible text. */
+export function stripAnsi(text) {
+  return String(text == null ? '' : text)
+    .replace(OSC_PATTERN, '')
+    .replace(CSI_PATTERN, '')
+    .replace(OTHER_ESCAPE_PATTERN, '');
+}
+
+/**
+ * Does this code point occupy two terminal columns?
+ *
+ * CJK, Hangul, Kana and most emoji are double-width. Getting this wrong is what
+ * makes a table of Indonesian and Chinese filenames drift apart.
+ */
+function isWideCodePoint(code) {
+  return (
+    (code >= 0x1100 && code <= 0x115f) ||   // Hangul Jamo
+    (code >= 0x2e80 && code <= 0xa4cf) ||   // CJK radicals … Yi
+    (code >= 0xac00 && code <= 0xd7a3) ||   // Hangul syllables
+    (code >= 0xf900 && code <= 0xfaff) ||   // CJK compatibility ideographs
+    (code >= 0xfe30 && code <= 0xfe6f) ||   // CJK compatibility forms
+    (code >= 0xff00 && code <= 0xff60) ||   // Fullwidth forms
+    (code >= 0xffe0 && code <= 0xffe6) ||
+    (code >= 0x1f300 && code <= 0x1f64f) || // emoji
+    (code >= 0x1f900 && code <= 0x1f9ff)
+  );
+}
+
+/**
+ * The East Asian AMBIGUOUS class (UAX #11).
+ *
+ * These render as ONE column beside Latin text and TWO beside CJK, depending on
+ * the terminal's font and locale — and every glyph in theme.js GLYPHS is in this
+ * class: `·` U+00B7, `▸` U+25B8, `✓` U+2713, `─` U+2500, `│` U+2502, `…` U+2026.
+ *
+ * Counting them narrow is right for a Western-configured terminal and is what
+ * every comparable library does, so that stays the default. But when the count
+ * is wrong the row is WIDER than measured, the terminal wraps it, and a wrapped
+ * row makes ChatPrompt.drawnRows (logical) disagree with the physical row count
+ * — which is what left a doubled hint row and glyph debris on screen. Callers
+ * that must not be wrong get the wide reading via the environment.
+ */
+function isAmbiguousCodePoint(code) {
+  return (
+    (code >= 0x00a1 && code <= 0x00ff && code !== 0x00ad) ||
+    (code >= 0x2010 && code <= 0x2027) ||
+    code === 0x2022 || code === 0x2026 ||
+    (code >= 0x2190 && code <= 0x21ff) ||   // arrows
+    (code >= 0x2200 && code <= 0x22ff) ||   // mathematical operators
+    (code >= 0x2460 && code <= 0x24ff) ||   // enclosed alphanumerics
+    (code >= 0x2500 && code <= 0x257f) ||   // box drawing
+    (code >= 0x2580 && code <= 0x259f) ||   // block elements
+    (code >= 0x25a0 && code <= 0x25ff) ||   // geometric shapes
+    (code >= 0x2600 && code <= 0x26ff) ||   // miscellaneous symbols
+    (code >= 0x2700 && code <= 0x27bf)      // dingbats (✓ ✕)
+  );
+}
+
+/**
+ * Should ambiguous-width code points be measured as two columns?
+ *
+ * Read once at import: an explicit override wins, otherwise a CJK locale is the
+ * signal, because that is the configuration in which a terminal's font actually
+ * renders these glyphs wide.
+ */
+function detectAmbiguousWide() {
+  const explicit = process.env.CAUSYNE_AMBIGUOUS_WIDE;
+  if (explicit === '1') return true;
+  if (explicit === '0') return false;
+  const locale = String(process.env.LC_ALL || process.env.LC_CTYPE || process.env.LANG || '');
+  return /^(ja|ko|zh)([_.-]|$)/i.test(locale);
+}
+
+export const AMBIGUOUS_IS_WIDE = detectAmbiguousWide();
+
+/** Columns one code point occupies, under the active ambiguous-width policy. */
+function columnsFor(code) {
+  if (isWideCodePoint(code)) return 2;
+  if (AMBIGUOUS_IS_WIDE && isAmbiguousCodePoint(code)) return 2;
+  return 1;
+}
+
+/** Columns this string will occupy once printed. Escapes count for nothing. */
+export function visibleWidth(text) {
+  const plain = stripAnsi(text);
+  let width = 0;
+  for (const character of plain) {
+    const code = character.codePointAt(0);
+    if (code === 0x200d) continue;          // zero-width joiner
+    if (code >= 0xfe00 && code <= 0xfe0f) continue; // variation selectors
+    width += columnsFor(code);
+  }
+  return width;
+}
+
+const RESET = '\x1b[0m';
+
+/**
+ * Cut to `width` columns without ever splitting an escape sequence.
+ *
+ * Walks the string escape-aware rather than slicing by index, and closes any
+ * style that was still open at the cut so the colour does not bleed into the
+ * next line.
+ */
+export function truncate(text, width, ellipsis = '…') {
+  const source = String(text == null ? '' : text);
+  if (width <= 0) return '';
+  if (visibleWidth(source) <= width) return source;
+
+  const ellipsisWidth = visibleWidth(ellipsis);
+  const budget = Math.max(0, width - ellipsisWidth);
+
+  let out = '';
+  let used = 0;
+  let sawEscape = false;
+  let index = 0;
+
+  while (index < source.length) {
+    if (source[index] === '\x1b') {
+      // Copy the whole sequence verbatim; it costs no columns.
+      const rest = source.slice(index);
+      const match = rest.match(/^\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/)
+        || rest.match(/^\x1b\[[0-?]*[ -/]*[@-~]/)
+        || rest.match(/^\x1b[@-Z\\-_]/);
+      if (match) {
+        out += match[0];
+        sawEscape = true;
+        index += match[0].length;
+        continue;
+      }
+    }
+
+    const character = String.fromCodePoint(source.codePointAt(index));
+    const charWidth = columnsFor(source.codePointAt(index));
+    if (used + charWidth > budget) break;
+
+    out += character;
+    used += charWidth;
+    index += character.length;
+  }
+
+  return out + (sawEscape ? RESET : '') + ellipsis;
+}
+
+/** Pad to an exact column count, measuring visible width rather than bytes. */
+export function padEnd(text, width) {
+  const gap = width - visibleWidth(text);
+  return gap > 0 ? String(text) + ' '.repeat(gap) : String(text);
+}
+
+
+export function wrap(text, width) {
+  if (width <= 0) return [String(text)];
+  const lines = [];
+
+  for (const paragraph of String(text == null ? '' : text).split('\n')) {
+    if (visibleWidth(paragraph) <= width) {
+      lines.push(paragraph);
+      continue;
+    }
+
+    let current = '';
+    for (const word of paragraph.split(' ')) {
+      const candidate = current ? `${current} ${word}` : word;
+
+      if (visibleWidth(candidate) <= width) {
+        current = candidate;
+        continue;
+      }
+      if (current) {
+        lines.push(current);
+        current = '';
+      }
+
+      let remainder = word;
+      while (visibleWidth(remainder) > width) {
+        lines.push(truncate(remainder, width, ''));
+        // truncate() gives us the head; drop the same number of characters.
+        let consumed = 0;
+        let cut = 0;
+        while (cut < remainder.length && consumed < width) {
+          const code = remainder.codePointAt(cut);
+          consumed += columnsFor(code);
+          cut += String.fromCodePoint(code).length;
+        }
+        remainder = remainder.slice(cut);
+      }
+      current = remainder;
+    }
+    if (current) lines.push(current);
+  }
+
+  return lines;
+}
+
+/**
+ * Word-wrap a block of text while preserving each line's own indentation.
+ *
+ * wrap() flattens indentation, which turns a nested list into a wall. This keeps
+ * the leading whitespace a line already has and indents its continuation rows by
+ * `hang` more, so a wrapped `/skills` entry still reads as one entry.
+ *
+ * Exists because command output was written to the terminal completely unwrapped
+ * — a `/skills` description reached 195 columns on a 102-column terminal and the
+ * terminal broke it at the right edge, mid-word, at column 0.
+ */
+export function wrapBlock(text, width, { hang = 2 } = {}) {
+  const rows = [];
+  for (const line of String(text == null ? '' : text).split('\n')) {
+    const indent = (line.match(/^[ \t]*/) || [''])[0];
+    const body = line.slice(indent.length);
+    if (!body) { rows.push(''); continue; }
+
+    const continuation = indent + ' '.repeat(hang);
+    // Wrap at the NARROWER of the two budgets so neither the first row nor a
+    // continuation row can exceed `width`.
+    const budget = Math.max(8, width - visibleWidth(continuation));
+    const parts = wrap(body, budget);
+    rows.push(indent + parts[0]);
+    for (const part of parts.slice(1)) rows.push(continuation + part);
+  }
+  return rows;
+}
+
+/**
+ * Make untrusted text safe to print.
+ *
+ * SECURITY, not cosmetics. Tool output reaches the terminal directly: a file
+ * read by fs_read, or the stdout of sysRun, is attacker-influenced content. If
+ * it carries escape sequences it can move the cursor, erase the screen, or
+ * overwrite lines that are already printed — including repainting an approval
+ * prompt the user just answered. Stripping escapes is what makes "the user saw
+ * what happened" true.
+ *
+ * Newlines and tabs survive; every other control character does not.
+ */
+/** Columns between terminal tab stops. Eight is the POSIX default everywhere. */
+const TAB_WIDTH = 8;
+
+/**
+ * Replace tabs with the spaces the terminal would have moved over.
+ *
+ * A TAB MOVES THE CURSOR WITHOUT WRITING ANYTHING. In a live region that
+ * redraws in place, that is not a formatting detail — it is corruption. The
+ * cursor jumps over cells the previous frame wrote and leaves them on screen,
+ * so `sw_vers` output rendered as:
+ *
+ *   ProductName:P_FIX_PLAN.mdmacOS
+ *   ProductVersion:EGOTIATION26.5.2
+ *
+ * where `P_FIX_PLAN.md` and `EGOTIATION` are the tails of filenames printed by
+ * the PREVIOUS command. Spaces overwrite; tabs do not.
+ *
+ * It also breaks measurement, which is worse. visibleWidth() counted a tab as
+ * one column while the terminal advanced up to eight — on that line the error
+ * was ten columns. A row the renderer believes fits therefore wraps, erase()
+ * miscounts how many rows to walk back, and it eats real conversation above the
+ * prompt. That is the live-region width invariant, broken by one byte.
+ *
+ * Tab stops are per LINE and reset after every newline, so this tracks the
+ * column rather than substituting a fixed run of spaces — which is what keeps
+ * columnar output actually lining up.
+ */
+export function expandTabs(text, tabWidth = TAB_WIDTH) {
+  const source = String(text == null ? '' : text);
+  if (!source.includes('\t')) return source;
+
+  let out = '';
+  let column = 0;
+  for (const char of source) {
+    if (char === '\t') {
+      const advance = tabWidth - (column % tabWidth);
+      out += ' '.repeat(advance);
+      column += advance;
+    } else if (char === '\n') {
+      out += char;
+      column = 0;
+    } else {
+      out += char;
+      column += 1;
+    }
+  }
+  return out;
+}
+
+export function sanitize(text) {
+  // Tabs are expanded rather than stripped: removing them would collapse
+  // columnar output into an unreadable run, and leaving them corrupts the
+  // frame. Expansion is the only option that preserves what the user meant to
+  // see. Everything else in this class is genuinely unwanted and is removed.
+  return expandTabs(stripAnsi(text))
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, '');
+}
+
+/** `/Users/example/Projects/x` → `~/Projects/x`. Long paths dominate a tool row. */
+export function shortenHome(value) {
+  const home = os.homedir();
+  const text = String(value == null ? '' : value);
+  if (home && text.startsWith(home)) return '~' + text.slice(home.length);
+  return text;
+}
+
+
+const SECRET_PATTERNS = [
+  [/\b(sk|pk|rk)-[A-Za-z0-9_-]{12,}/g, (m) => `${m.slice(0, 5)}…${m.slice(-4)}`],
+  [/\b(gh[pousr]|xox[baprs])_[A-Za-z0-9]{12,}/g, (m) => `${m.slice(0, 7)}…`],
+  [/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{12,}/gi, (m) => `${m.split(/\s+/)[0]} …`],
+  [/\b(api[_-]?key|token|secret|password|passwd)\s*[=:]\s*["']?[^\s"']{6,}/gi,
+    (m) => `${m.split(/[=:]/)[0]}=…`]
+];
+
+export function redactSecrets(text) {
+  let out = String(text == null ? '' : text);
+  for (const [pattern, replace] of SECRET_PATTERNS) {
+    out = out.replace(pattern, replace);
+  }
+  return out;
+}
+
+/** sanitize + redact — the pipeline every untrusted string goes through. */
+export function safeDisplay(text) {
+  return redactSecrets(sanitize(text));
+}