@synqa/cli 0.0.0-stage → 1.1.0

package/dist/journal.js

@@ -0,0 +1,61 @@
+// In-memory journal of the files the agent wrote, so /undo can put the last one back.
+import { existsSync, readFileSync, rmSync, statSync } from "node:fs";
+import { relative } from "node:path";
+import { confine, writeConfined } from "./paths.js";
+
+                            
+                                     
+                                                        
+                
+  
+
+export const MAX_JOURNAL = 100;
+export const MAX_SNAPSHOT_BYTES = 5_000_000;
+
+// The current bytes of a file, null when it does not exist, "too-large" when it is not safe to keep.
+export function snapshot(path        )                              {
+  if (!existsSync(path)) return null;
+  if (statSync(path).size > MAX_SNAPSHOT_BYTES) return "too-large";
+  return readFileSync(path);
+}
+
+                        
+                                                                                      
+                                                                                
+
+export class EditJournal {
+          entries                 = [];
+
+  get size()         {
+    return this.entries.length;
+  }
+
+  record(e              )       {
+    this.entries.push(e);
+    if (this.entries.length > MAX_JOURNAL) this.entries.shift();
+  }
+
+  peek()                           {
+    return this.entries[this.entries.length - 1];
+  }
+
+  // Reverts the newest entry. If the file changed since the agent wrote it (the user edited it, or a
+  // command did), the caller must confirm first: `force` is that answer.
+  undo(cwd        , force         )             {
+    const e = this.peek();
+    if (!e) return { ok: false, reason: "empty", message: "nothing to undo" };
+    try {
+      const abs = confine(cwd, e.path);
+      const current = existsSync(abs) ? readFileSync(abs) : null;
+      if (!force && (current === null || !current.equals(e.after))) {
+        return { ok: false, reason: "changed-since", message: "the file changed after the agent wrote it" };
+      }
+      if (e.before === null) rmSync(abs, { force: true });
+      else writeConfined(cwd, e.path, e.before);
+    } catch (err) {
+      return { ok: false, reason: "error", message: err instanceof Error ? err.message : String(err) };
+    }
+    this.entries.pop();
+    return { ok: true, path: relative(cwd, e.path) || e.path, removed: e.before === null, before: e.before, after: e.after };
+  }
+}

package/dist/main.js

@@ -0,0 +1,254 @@
+import { createInterface } from "node:readline/promises";
+import { runAgent } from "./agent.js";
+import { checkKey } from "./api.js";
+import { announceNotes, freshHistory, runCommand, statusParts } from "./commands.js";
+                                                  
+import { looksLikeKey, readConfig, resolveApiKey, writeConfig, configPath } from "./config.js";
+import { EditJournal } from "./journal.js";
+import { unsafeStartDir } from "./paths.js";
+import { sanitize } from "./sanitize.js";
+import { formatStatus, StatusBar } from "./statusbar.js";
+import { DEFAULT_TIER, findEffort, findTier, routingLabel } from "./tiers.js";
+import { accent, dim, stone } from "./theme.js";
+                                        
+import { fetchAccount } from "./account.js";
+import { balanceFrom, formatFooter, makeUi, readVersion, renderBanner, Spinner, styleOf, TurnRenderer } from "./ui.js";
+                                       
+
+const VERSION = readVersion();
+
+// The balance fetch gets this long at startup and after a turn; the banner never waits longer.
+const BALANCE_TIMEOUT_MS = 2000;
+
+const HELP = `Usage:
+  synqa                     interactive session in the current folder
+  synqa "do something"      one-shot task
+  synqa login               save your API key
+Options:
+  -y, --yes                 do not ask before write, edit and bash
+  -m, --model <tier>        blink | sonata | aeon (default blink)
+  -e, --effort <level>      default | low | medium (default default)
+  --allow-home              allow starting in your home folder or the filesystem root
+  -h, --help   -v, --version
+In a session: /model, /effort, /status, /init, /compact, /undo, /clear, /help, /exit`;
+
+// Masked single-line input: nothing typed is echoed.
+export function readSecret(promptText        )                  {
+  return new Promise((resolve, reject) => {
+    const stdin = process.stdin;
+    if (!stdin.isTTY) {
+      reject(new Error("login needs an interactive terminal (or set SYNQA_API_KEY)"));
+      return;
+    }
+    process.stdout.write(promptText);
+    let value = "";
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding("utf8");
+    const onData = (chunk        ) => {
+      for (const ch of chunk) {
+        if (ch === "\r" || ch === "\n") {
+          stdin.setRawMode(false);
+          stdin.pause();
+          stdin.off("data", onData);
+          process.stdout.write("\n");
+          resolve(value.trim());
+          return;
+        }
+        if (ch === "\u0003") {
+          stdin.setRawMode(false);
+          process.stdout.write("\n");
+          reject(new Error("cancelled"));
+          return;
+        }
+        if (ch === "\u007f" || ch === "\b") value = value.slice(0, -1);
+        else if (ch >= " ") value += ch;
+      }
+    };
+    stdin.on("data", onData);
+  });
+}
+
+// The error text can come from the network, so it is sanitized before printing.
+export function loginFailureMessage(err         )         {
+  return sanitize(`Could not verify the key: ${err instanceof Error ? err.message : String(err)}`);
+}
+
+export async function login()                  {
+  const key = await readSecret("Paste your Synqa API key (input is hidden): ");
+  if (!looksLikeKey(key)) {
+    console.error("That does not look like a Synqa key (expected synqa_live_...).");
+    return 1;
+  }
+  try {
+    await checkKey(key);
+  } catch (err) {
+    console.error(loginFailureMessage(err));
+    return 1;
+  }
+  const file = writeConfig({ ...readConfig(), apiKey: key });
+  console.log(`Key verified and saved to ${file}`);
+  return 0;
+}
+
+                                                                                                                                 
+
+export function parseArgs(argv          )       {
+  const a       = { allowHome: false, yes: false, model: "", effort: "", help: false, version: false, rest: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i]          ;
+    if (t === "-y" || t === "--yes") a.yes = true;
+    else if (t === "--allow-home") a.allowHome = true;
+    else if (t === "-h" || t === "--help") a.help = true;
+    else if (t === "-v" || t === "--version") a.version = true;
+    else if (t === "-m" || t === "--model") a.model = argv[++i] ?? "";
+    else if (t === "-e" || t === "--effort") a.effort = argv[++i] ?? "";
+    else a.rest.push(t);
+  }
+  return a;
+}
+
+export async function main(argv          )                  {
+  const args = parseArgs(argv);
+  if (args.help) { console.log(HELP); return 0; }
+  if (args.version) { console.log(VERSION); return 0; }
+  if (args.rest[0] === "login") return login();
+
+  const unsafe = unsafeStartDir(process.cwd());
+  if (unsafe && !args.allowHome) {
+    console.error(`Refusing to start in ${unsafe}: the agent could read your keys and settings there. cd into a project folder, or pass --allow-home if you really mean it.`);
+    return 1;
+  }
+  const apiKey = resolveApiKey();
+  if (!apiKey) {
+    console.error(`No API key. Run "synqa login" or set SYNQA_API_KEY. (config: ${configPath()})`);
+    return 1;
+  }
+  const ui = makeUi(process.env, process.stdout);
+  const style        = styleOf(ui);
+  const tier = findTier(args.model || readConfig().tier || DEFAULT_TIER);
+  if (!tier) { console.error(`Unknown tier "${args.model}". Use blink, sonata or aeon.`); return 1; }
+  const effort = args.effort ? findEffort(args.effort) : "default";
+  if (!effort) { console.error(`Unknown effort "${args.effort}". Use default, low or medium.`); return 1; }
+
+  const interactive = Boolean(process.stdin.isTTY) && args.rest.length === 0;
+  const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: Boolean(process.stdin.isTTY) });
+  const say = (s        ) => console.log(s);
+  // Chrome (spinner, cards, footer) is for interactive terminals only. Pipes and one-shot runs get
+  // the plain text output they had before.
+  const chrome = interactive && ui.tty;
+  const spinner = new Spinner(process.stdout, { enabled: chrome, ui });
+  const renderer = new TurnRenderer(process.stdout, ui, spinner);
+  const inCard = (t        ) => (chrome ? renderer.body(t) : t);
+  // `detail` is the coloured diff the tools built; the question is sanitized, the diff is not
+  // (the tools already escaped every file character in it).
+  const confirm = async (q        , detail         )                   => {
+    if (!process.stdin.isTTY) return false;
+    spinner.stop();
+    if (detail) say(inCard(detail));
+    const ans = await rl.question(`${accent(style, "?")} ${sanitize(q)} [y/N] `);
+    return /^y(es)?$/i.test(ans.trim());
+  };
+
+  const cwd = process.cwd();
+  const st               = {
+    apiKey, cwd, tier, effort, history: [], journal: new EditJournal(),
+    total: { prompt: 0, completion: 0 }, last: { prompt: 0, completion: 0 }, routing: "?", notesChars: 0, notesShown: 0,
+  };
+  st.history = freshHistory(st);
+  const ctx = { cwd, confirm, yes: args.yes, color: style.color, journal: st.journal, show: (t        ) => say(inCard(t)), get notesLoaded() { return st.notesChars > 0; } };
+
+  // The pinned bar needs a terminal on both ends; otherwise the status is an ordinary line.
+  const bar = new StatusBar(
+    process.stdout,
+    interactive && Boolean(process.stdout.isTTY) && process.env.TERM !== "dumb",
+    (s) => dim(style, s),
+  );
+  const refresh = () => {
+    if (bar.enabled) bar.update(formatStatus(statusParts(st), (process.stdout.columns ?? 80) - 1));
+  };
+  const restore = () => { spinner.stop(); bar.uninstall(); };
+  process.on("exit", restore);
+  process.stdout.on("resize", () => { bar.resize(); refresh(); });
+
+  // Known balance for the footer; refreshed in the background after each turn, never awaited.
+  let balance          = { kind: "unavailable" };
+  const loadBalance = async ()                   => balanceFrom(await fetchAccount(apiKey, undefined, BALANCE_TIMEOUT_MS));
+  const refreshBalance = () => { void loadBalance().then((b) => { balance = b; }, () => {}); };
+
+  const turn = async (text        )                => {
+    st.history.push({ role: "user", content: text });
+    try {
+      const r = await runAgent({
+        apiKey, tier: st.tier, effort: st.effort, history: st.history, ctx,
+        events: chrome
+          ? {
+            onRequest: () => renderer.requestStart(),
+            onText: (t) => renderer.text(t),
+            onTool: (name, a) => renderer.toolStart(name, a),
+            onToolResult: (name, _a, result) => renderer.toolResult(name, result),
+            onTurn: () => renderer.requestEnd(),
+          }
+          : {
+            onText: (t) => process.stdout.write(sanitize(t)),
+            onTool: (name, a) => process.stdout.write(`\n${dim(style, `> ${sanitize(name)} ${sanitize(a.length > 120 ? a.slice(0, 117) + "..." : a)}`)}\n`),
+            onTurn: () => {},
+          },
+      });
+      st.total = { prompt: st.total.prompt + r.total.prompt, completion: st.total.completion + r.total.completion };
+      st.last = r.lastUsage;
+      st.routing = routingLabel(r.routing);
+      st.ttftMs = r.ttftMs;
+      st.tokPerSec = r.tokPerSec;
+      if (chrome) {
+        renderer.turnEnd();
+        const footer = formatFooter({
+          ttftMs: r.ttftMs, tokPerSec: r.tokPerSec, routing: st.routing,
+          creditLeft: balance.kind === "ok" ? balance.account.creditRemaining : undefined,
+        }, ui);
+        if (footer) say(stone(style, footer));
+        refreshBalance();
+      } else {
+        process.stdout.write("\n");
+      }
+    } catch (err) {
+      spinner.stop();
+      console.error(`\nerror: ${sanitize(err instanceof Error ? err.message : String(err))}`);
+    }
+    refresh();
+  };
+
+  try {
+    if (!interactive) {
+      const prompt = args.rest.join(" ");
+      if (!prompt) { console.error("Nothing to do. Pass a task or run in a terminal."); return 1; }
+      announceNotes(st, say);
+      await turn(prompt);
+      say(dim(style, formatStatus(statusParts(st))));
+      return 0;
+    }
+
+    // The balance may take a moment; the banner waits at most BALANCE_TIMEOUT_MS for it.
+    balance = await loadBalance();
+    for (const line of renderBanner({ version: VERSION, tier: st.tier, cwd, notesChars: st.notesChars, balance }, ui)) say(line);
+    say(dim(style, "Type /help for commands."));
+    announceNotes(st, say);
+    bar.install();
+    refresh();
+    for (;;) {
+      // Without a pinned bar the status is printed above each prompt instead.
+      if (!bar.enabled) say(dim(style, formatStatus(statusParts(st))));
+      let line        ;
+      try { line = (await rl.question(`${accent(style, ui.unicode ? "❯" : ">")} `)).trim(); } catch { break; }
+      if (!line) continue;
+      const r = await runCommand(line, st, { print: say, confirm, style });
+      refresh();
+      if (r.exit) break;
+      if (!r.handled) await turn(line);
+    }
+    return 0;
+  } finally {
+    restore();
+    rl.close();
+  }
+}

package/dist/paths.js

@@ -0,0 +1,131 @@
+import { closeSync, constants, lstatSync, openSync, realpathSync, writeSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
+import { configDir } from "./config.js";
+
+export class ConfineError extends Error {}
+
+function realOfExisting(p        )         {
+  // Resolve symlinks on the nearest existing ancestor, then re-append the missing tail.
+  // A missing component that is itself a symlink is a dangling link: refuse it, because a
+  // write would follow it to wherever it points.
+  let cur = p;
+  const tail           = [];
+  for (;;) {
+    try {
+      const real = realpathSync(cur);
+      return tail.length ? join(real, ...tail.reverse()) : real;
+    } catch {
+      let isLink = false;
+      try {
+        isLink = lstatSync(cur).isSymbolicLink();
+      } catch {
+        isLink = false;
+      }
+      if (isLink) throw new ConfineError(`path goes through a dangling symlink: ${p}`);
+      const parent = dirname(cur);
+      if (parent === cur) return p;
+      tail.push(cur.slice(parent.length).replace(/^[\\/]+/, ""));
+      cur = parent;
+    }
+  }
+}
+
+// Returns the absolute path if it stays inside root (after ".." and symlink resolution), else throws.
+export function confine(root        , requested        )         {
+  const realRoot = realpathSync(root);
+  const abs = isAbsolute(requested) ? resolve(requested) : resolve(realRoot, requested);
+  const real = realOfExisting(abs);
+  const rel = relative(realRoot, real);
+  if (rel === "") return real;
+  if (rel === ".." || rel.startsWith(".." + sep) || isAbsolute(rel)) {
+    throw new ConfineError(`path escapes the working directory: ${requested}`);
+  }
+  return real;
+}
+
+// Re-confines right before writing and refuses to follow a symlink as the last component.
+export function writeConfined(root        , requested        , content                 )         {
+  const p = confine(root, requested);
+  const fd = openSync(p, constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | constants.O_NOFOLLOW, 0o644);
+  try {
+    writeSync(fd, content);
+  } finally {
+    closeSync(fd);
+  }
+  return p;
+}
+
+// One form for every comparison: NFKC (full-width and compatibility characters become plain ones)
+// and lower case, because a client Mac's file system is case-insensitive: ".ENV" is ".env".
+export function fold(s        )         {
+  return s.normalize("NFKC").toLowerCase();
+}
+
+// Folders whose contents are credentials.
+const SENSITIVE_DIRS = new Set([".ssh", ".aws", ".gnupg"]);
+// Exact file names that hold secrets (compared folded).
+const SENSITIVE_NAMES = new Set([
+  ".env", ".envrc", ".netrc", ".npmrc", ".pypirc", ".git-credentials", ".dev.vars", "keys.json", "credentials.json", ".yarnrc.yml", ".pgpass", ".my.cnf",
+]);
+const EXAMPLE_SUFFIX = /\.(example|sample|template|dist)$/;
+
+// Files and folders that hold secrets: .env files, private keys, cloud, package manager and
+// container credentials, and this CLI's own config (which holds the API key). Names only, no file
+// is opened. Every segment is folded first (see fold).
+export function isSensitivePath(abs        , cfg         = configDir())          {
+  const norm = fold(abs.split(sep).join("/"));
+  const parts = norm.split("/").filter(Boolean);
+  if (parts.some((d) => SENSITIVE_DIRS.has(d))) return true;
+  for (let i = 0; i + 1 < parts.length; i++) {
+    if (parts[i] === ".config" && parts[i + 1] === "synqa") return true;
+    if (parts[i] === ".kube" && parts[i + 1] === "config") return true;
+    if (parts[i] === ".docker" && parts[i + 1] === "config.json") return true;
+  }
+  const c = fold(cfg.split(sep).join("/")).replace(/\/+$/, "");
+  if (c && (norm === c || norm.startsWith(c + "/"))) return true;
+  const name = parts[parts.length - 1] ?? "";
+  // Remotes can hold tokens: .git/config, .git/config.worktree, .git/worktrees/<name>/config, at any depth.
+  if (parts.slice(0, -1).includes(".git") && (name === "config" || name.startsWith("config."))) return true;
+  if (SENSITIVE_NAMES.has(name)) return true;
+  if (name.startsWith(".env.") && !EXAMPLE_SUFFIX.test(name)) return true;
+  if (/\.(pem|key|p12|pfx|tfvars|tfstate)$/.test(name)) return true;
+  if (/^secrets\./.test(name) && !EXAMPLE_SUFFIX.test(name)) return true;
+  return /^id_[a-z0-9_]+$/.test(name); // id_rsa, id_ed25519; id_rsa.pub is not matched
+}
+
+// Names a shell command can use to reach a secret, including globs that expand to them. Heuristic:
+// it makes an unattended (--yes) command ask when it looks at secrets, it does not make bash safe.
+const SECRET_WORDS = [
+  /\.env/, /\.ssh/, /\.aws/, /\.gnupg/, /\.kube/, /\.docker/, /\.netrc/, /\.npmrc/, /\.pypirc/, /\.git-credentials/,
+  /\.dev\.vars/, /keys\.json/, /credentials/, /\.tfvars/, /\bsecrets?\b/, /\.(pem|key|p12|pfx)\b/, /\bid_[a-z0-9]/,
+  /\.config\/synqa/, /synqa\/config/, /(^|[\s/])\.[\w.-]*[*?[]/, /~\/?\./,
+];
+
+export function commandTouchesSecrets(command        , cfg         = configDir())          {
+  // Quotes and backslashes are dropped first so .e""nv and .\env read as .env.
+  const c = fold(command).replace(/["'\\`]/g, "");
+  if (SECRET_WORDS.some((re) => re.test(c))) return true;
+  const dir = fold(cfg);
+  return dir !== "" && c.includes(dir);
+}
+
+// A start folder this CLI refuses without --allow-home: the home folder or the filesystem root.
+// Returns the reason, or undefined when the folder is fine.
+export function unsafeStartDir(cwd        , home         = homedir())                     {
+  let real        ;
+  let realHome        ;
+  try {
+    real = realpathSync(cwd);
+  } catch {
+    return undefined;
+  }
+  try {
+    realHome = realpathSync(home);
+  } catch {
+    realHome = home;
+  }
+  if (real === parse(real).root) return "the filesystem root";
+  if (real === realHome) return "your home folder";
+  return undefined;
+}

package/dist/sanitize.js

@@ -0,0 +1,53 @@
+// Model-controlled text must never reach the terminal as control sequences.
+
+// OSC (ESC ] ... BEL or ST), CSI (ESC [ ... final byte), and any other two-byte ESC sequence.
+const ESC_SEQ = /\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)?|\x1b\[[0-?]*[ -/]*[@-~]?|\x1b[@-_]?/g;
+// C0 except \n and \t, DEL, and C1.
+const CONTROL = /[\x00-\x08\x0b-\x1f\x7f-\x9f]/g;
+// Bidi controls and invisible characters that can reorder or hide text, as inclusive code point
+// ranges: U+061C, U+200B-200F, U+2028-2029, U+202A-202E, U+2060-2064, U+2066-2069, U+FEFF. Built from numbers so this
+// source file itself holds none of them.
+const INVISIBLE_RANGES                                           = [
+  [0x061c, 0x061c],
+  [0x200b, 0x200f],
+  [0x2028, 0x2029],
+  [0x202a, 0x202e],
+  [0x2060, 0x2064],
+  [0x2066, 0x2069],
+  [0xfeff, 0xfeff],
+];
+const hex4 = (n        ) => n.toString(16).padStart(4, "0");
+const INVISIBLE = new RegExp(
+  "[" + INVISIBLE_RANGES.map(([a, b]) => `\\u${hex4(a)}-\\u${hex4(b)}`).join("") + "]",
+  "g",
+);
+
+export function sanitize(s        )         {
+  return s.replace(ESC_SEQ, "").replace(CONTROL, "").replace(INVISIBLE, "");
+}
+
+// For text the user must judge before approving (shell commands, paths): show escapes literally.
+export function visibleEscapes(s        )         {
+  return s
+    .replace(/[\x00-\x08\x0a-\x1f\x7f-\x9f]/g, (c) => {
+      if (c === "\n") return "\\n";
+      if (c === "\r") return "\\r";
+      return "\\x" + c.charCodeAt(0).toString(16).padStart(2, "0");
+    })
+    .replace(INVISIBLE, (c) => "\\u" + hex4(c.charCodeAt(0)));
+}
+
+// Untrusted text that goes inside a fenced block of the prompt (AGENTS.md, the compact summary).
+// Order matters: NFKC first (full-width and compatibility forms become plain ones), then every
+// format and default-ignorable character is removed (soft hyphen, zero-width and bidi marks, the
+// word joiner range, BOM: they could split a tag so a match misses it), then the cap, so the
+// normalization cannot grow the text past it, and last every "<" becomes "\u2039" so no tag, in any
+// spelling, can open or close the fence.
+export function fenceText(s        , max        )         {
+  return s
+    .normalize("NFKC")
+    .replace(/[\p{Cf}\u00ad\u034f\u115f\u1160\u17b4\u17b5\u180b-\u180f\u2060-\u206f\u3164\ufe00-\ufe0f\uffa0]/gu, "")
+    .trim()
+    .slice(0, max)
+    .replace(/</g, "\u2039");
+}

package/dist/statusbar.js

@@ -0,0 +1,114 @@
+// The status bar: one line with the tier, routing mode, TTFT, tok/s and session tokens. On a
+// terminal it is pinned to the bottom row (the scroll region stops one row short of it); anywhere
+// else it is printed as an ordinary line by the caller, so nothing here needs a terminal to be tested.
+                                               
+
+                           
+             
+                                                   
+                 
+                  
+                     
+                                               
+  
+
+// 1234567 -> "1,234,567" without relying on the locale.
+export function groupDigits(n        )         {
+  return String(Math.max(0, Math.round(n))).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+}
+
+export function formatTtft(ms                    )         {
+  return ms === undefined || !Number.isFinite(ms) || ms < 0 ? "-" : `${(ms / 1000).toFixed(2)}s`;
+}
+
+export function formatRate(tps                    )         {
+  return tps === undefined || !Number.isFinite(tps) || tps <= 0 ? "-" : `${tps.toFixed(1)} tok/s`;
+}
+
+// Fits `width` columns by dropping segments from the least important end; the tier always stays.
+export function formatStatus(p             , width         )         {
+  const tier = p.tier.display;
+  const effort = p.effort === "default" ? "" : `effort ${p.effort}`;
+  const full = [tier, effort, p.routing, `TTFT ${formatTtft(p.ttftMs)}`, formatRate(p.tokPerSec), `${groupDigits(p.tokens)} tokens`];
+  const variants = [
+    full,
+    [tier, p.routing, `TTFT ${formatTtft(p.ttftMs)}`, formatRate(p.tokPerSec), `${groupDigits(p.tokens)} tokens`],
+    [tier, p.routing, formatRate(p.tokPerSec), `${groupDigits(p.tokens)} tok`],
+    [tier, p.routing, `${groupDigits(p.tokens)} tok`],
+    [tier, p.routing],
+  ];
+  const join = (parts          ) => parts.filter((x) => x !== "").join(" | ");
+  if (width === undefined) return join(full);
+  for (const v of variants) {
+    const t = join(v);
+    if (t.length <= width) return t;
+  }
+  const last = join(variants[variants.length - 1]            );
+  return width > 1 ? last.slice(0, width - 1) + "…" : last.slice(0, width);
+}
+
+                                                                                 
+
+const ESC = "\x1b";
+
+// Pins `text` to the last terminal row. All escape sequences are fixed strings made here; the text
+// comes from formatStatus (tier names and numbers), never from the model.
+export class StatusBar {
+          out     ;
+          on         ;
+          text = "";
+          installed = false;
+          paint                       ;
+
+  constructor(out     , enabled         , paint                        = (s) => s) {
+    this.out = out;
+    this.paint = paint;
+    // Needs room for at least the bar plus a few lines of scrollback.
+    this.on = enabled && (out.rows ?? 0) >= 6 && (out.columns ?? 0) >= 20;
+  }
+
+  get enabled()          {
+    return this.on;
+  }
+
+          rows()         {
+    return this.out.rows ?? 24;
+  }
+
+          cols()         {
+    return this.out.columns ?? 80;
+  }
+
+  install()       {
+    if (!this.on || this.installed) return;
+    this.installed = true;
+    // A newline guarantees a spare row below the cursor, then the cursor goes back up.
+    this.out.write(`\n${ESC}[1A${ESC}7${ESC}[1;${this.rows() - 1}r${ESC}8`);
+    this.draw();
+  }
+
+  update(text        )       {
+    this.text = text;
+    this.draw();
+  }
+
+  // Terminal size changed: move the scroll region and repaint.
+  resize()       {
+    if (!this.on || !this.installed) return;
+    this.out.write(`${ESC}7${ESC}[1;${this.rows() - 1}r${ESC}8`);
+    this.draw();
+  }
+
+          draw()       {
+    if (!this.on || !this.installed) return;
+    const line = this.text.length > this.cols() - 1 ? this.text.slice(0, this.cols() - 2) + "…" : this.text;
+    this.out.write(`${ESC}7${ESC}[${this.rows()};1H${ESC}[2K${this.paint(line)}${ESC}8`);
+  }
+
+  // Gives the whole screen back and clears the bar row.
+  uninstall()       {
+    if (!this.on || !this.installed) return;
+    this.installed = false;
+    this.out.write(`${ESC}7${ESC}[r${ESC}[${this.rows()};1H${ESC}[2K${ESC}8`);
+  }
+}