@bivy/bivy 0.20.1-staging.7 → 0.20.1-staging.8

package/bin/bivy.mjs

@@ -42,7 +42,7 @@ import { removeInstallAndState } from "./uninstall-paths.mjs";
 import { findAvailablePort, reconcilePort } from "./port-picker.mjs";
 import { parseTailscaleStatus, serveConflict, serveFailureHint, serveOffArgs, serveOnArgs, serveState } from "./tailscale.mjs";
 import { resolveAttachSessionId } from "./attach-session-id.mjs";
-import { detectInstallKind as classifyInstallKind, npmGlobalPrefix } from "./install-kind.mjs";
+import { detectInstallKind as classifyInstallKind, managedInstall, npmGlobalPrefix } from "./install-kind.mjs";
 import { hasConfiguredService as configuredServiceExists } from "./service-state.mjs";
 import { COMMANDS, EXIT, cliError, completionWords, describeCli, describeCommand, describeTools, renderHelp, resolveCommand, subcommandTable, suggestCommands, toolArgv, wantsJson } from "./cli-commands.mjs";
 
@@ -77,6 +77,7 @@ process.env.BIVY_DATA_DIR = appDir;
 //   - "npx"        ephemeral `npx bivy` run (repoRoot under an npm _npx cache)
 //   - "npm-global" `npm i -g @bivy/bivy` (repoRoot is below node_modules/@bivy)
 //   - "packaged"   install.sh tarball tree (user-owned, self-preserving)
+//   - "managed"    a system package (the AUR's `bivy`), updated by its manager
 function detectInstallKind() {
   return classifyInstallKind(repoRoot);
 }
@@ -2133,6 +2134,31 @@ async function fetchJson(baseUrl, pathName, token) {
 //   --json          machine-readable list, no prompt
 //   --limit/-n N    cap how many saved sessions to show (default: unlimited — all of them)
 //   <n> | <id>      select non-interactively (index in the list, or a session id)
+// `bivy tui` — every session on this machine and your direct nodes in one
+// terminal view: live transcripts, approvals, messages to the agent.
+async function cmdTui(args = []) {
+  if (args.includes("-h") || args.includes("--help")) {
+    console.log("Usage: bivy tui\n\nA terminal view of the sessions on this machine and on the nodes you added with 'bivy nodes add': live transcripts, approvals and messages to the agent, all from the keyboard. Press ? inside for keys.");
+    return;
+  }
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    console.error(c.red("bivy tui needs an interactive terminal."));
+    process.exitCode = EXIT.usage;
+    return;
+  }
+  const config = loadConfig();
+  if (!(await ensureNodeRunning(config))) {
+    console.error(c.red(`Could not start the Bivy node at ${url(config)}.`));
+    process.exitCode = EXIT.unavailable;
+    return;
+  }
+  const token = await localDeviceToken(config);
+  const info = await fetchJson(url(config), "/api/node/info", token).catch(() => ({}));
+  const direct = Object.entries(loadNodes().nodes).map(([name, node]) => ({ name, base: node.url, token: node.token }));
+  const { runTui } = await import("./tui/app.mjs");
+  await runTui({ machines: [{ name: info?.name || "this machine", base: url(config), token }, ...direct] });
+}
+
 async function cmdSessions(args = [], opts = {}) {
   if (args.includes("-h") || args.includes("--help")) {
     console.log(
@@ -5314,6 +5340,13 @@ async function cmdUpdate(args = []) {
     console.log("Usage: bivy update [--force|--no-wait] [--staging|--stable|--channel <name>]\n\nUpdate Bivy + install deps + restart service. Stays on the release channel recorded at install time (default 'latest'); --staging/--stable/--channel switch channels and are remembered for future updates. Waits for active sessions to finish a turn first; --force/--no-wait skips the wait. See 'bivy update:log' for the last run's output.");
     return;
   }
+  const managed = managedInstall(repoRoot);
+  if (managed) {
+    console.log(`Bivy is installed by ${managed.manager} here, so it updates through it${managed.update ? `: ${c.cyan(managed.update)}` : "."}`);
+    console.log(c.dim("Then run 'bivy restart' to pick up the new version."));
+    process.exitCode = EXIT.failed;
+    return;
+  }
   // Inside a Bivy web/PWA terminal the shell is a child of the node's own
   // process, so `restartService()` — the final step of an update — tears down
   // this very terminal. Run inline and you lose all output the moment it lands.
@@ -6414,6 +6447,9 @@ Unlike 'bivy run', these commands operate on governed background Runs with check
     case "link":
       await cmdLinkPhone(args);
       break;
+    case "tui":
+      await cmdTui(args);
+      break;
     case "tailscale":
       await cmdTailscale(args);
       break;

package/bin/cli-commands.mjs

@@ -65,6 +65,7 @@ export const COMMANDS = [
   { name: "run", group: "sessions", scope: "node", usage: "run <agent> [--chat] [--name …] [--model …] [--node …] [--workspace …]", summary: "Run an agent (native CLI/TUI) as a session the app can see" },
   { name: "exec", group: "sessions", scope: "node", json: true, usage: 'exec "<prompt>" [--agent …] [--session …]', summary: "One-shot headless session: prints the answer to stdout" },
   { name: "send", group: "sessions", scope: "node", json: true, usage: 'send <id> "<message>"', summary: "Send a prompt to an existing session and stream the reply" },
+  { name: "tui", group: "sessions", scope: "node", usage: "tui", summary: "Sessions across your machines in the terminal: transcripts, approvals, messages" },
   { name: "sessions", aliases: ["ls"], group: "sessions", scope: "node", json: true, usage: "sessions [--json]", summary: "List recent sessions (live and saved) and resume one" },
   { name: "resume", group: "sessions", scope: "node", usage: "resume [n|id]", summary: "Resume a session directly (default: most recent)" },
   { name: "kill", group: "sessions", scope: "node", usage: "kill <id> [--delete]", summary: "Stop a session or terminal" },

package/bin/install-kind.mjs

@@ -3,9 +3,29 @@
 import fs from "node:fs";
 import path from "node:path";
 
+/** The file a system package (pacman, …) writes into the install it owns. */
+export const MANAGED_INSTALL_FILE = ".bivy-install.json";
+
+/**
+ * `{ manager, update }` when a system package manager owns this install, so
+ * Bivy must not replace its files; null otherwise.
+ */
+export function managedInstall(repoRoot, readFileSync = fs.readFileSync) {
+  try {
+    const data = JSON.parse(readFileSync(path.join(repoRoot, MANAGED_INSTALL_FILE), "utf8"));
+    if (typeof data?.manager === "string" && data.manager) {
+      return { manager: data.manager, update: typeof data.update === "string" ? data.update : "" };
+    }
+  } catch {
+    /* not managed */
+  }
+  return null;
+}
+
 /** Classify a Bivy package root without assuming unscoped npm package layout. */
 export function detectInstallKind(repoRoot, existsSync = fs.existsSync) {
   if (existsSync(path.join(repoRoot, ".git"))) return "git";
+  if (existsSync(path.join(repoRoot, MANAGED_INSTALL_FILE))) return "managed";
 
   // npm installs an unscoped package at node_modules/name and a scoped package
   // at node_modules/@scope/name. Bivy uses the latter layout.

package/bin/tui/app.mjs

@@ -0,0 +1,189 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+// `bivy tui`: the terminal around model.mjs and render.mjs. It polls each
+// machine's node API, keeps the selected session's transcript current, turns
+// keys into effects and draws only the lines that changed.
+
+import { initialState, reduceKey, selectedSession, sessionKey, withData, isWorking } from "./model.mjs";
+import { renderFrame } from "./render.mjs";
+import { transcriptEntries } from "./transcript.mjs";
+
+const POLL_MS = 1500;
+const SPIN_MS = 120;
+
+const KEYS = {
+  "\x1b[A": "up", "\x1b[B": "down", "\x1b[C": "right", "\x1b[D": "left",
+  "\x1bOA": "up", "\x1bOB": "down", "\x1bOC": "right", "\x1bOD": "left",
+  "\x1b[5~": "pageup", "\x1b[6~": "pagedown",
+  "\r": "enter", "\n": "enter", "\t": "tab", "\x7f": "backspace", "\b": "backspace",
+  "\x1b": "esc", "\x03": "ctrl-c", "\x04": "ctrl-d", "\x15": "ctrl-u", " ": "space",
+};
+
+/** Raw terminal input as key names; a paste arrives as its characters. */
+export function parseKeys(data) {
+  const text = String(data);
+  if (KEYS[text]) return [KEYS[text]];
+  if (text.startsWith("\x1b")) return [];
+  return [...text].map((ch) => KEYS[ch] ?? ch).filter((k) => k.length > 1 || k >= " ");
+}
+
+async function call(machine, method, path, body) {
+  const res = await fetch(`${machine.base}${path}`, {
+    method,
+    headers: { "content-type": "application/json", ...(machine.token ? { authorization: `Bearer ${machine.token}` } : {}) },
+    ...(body ? { body: JSON.stringify(body) } : {}),
+    signal: AbortSignal.timeout(method === "GET" ? 4000 : 15000),
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(data?.error || `HTTP ${res.status}`);
+  return data;
+}
+
+/** Sessions and approvals from every machine; one that doesn't answer is marked offline. */
+async function snapshot(machines) {
+  const results = await Promise.all(machines.map(async (machine) => {
+    try {
+      const [sessions, approvals] = await Promise.all([call(machine, "GET", "/api/sessions"), call(machine, "GET", "/api/approvals")]);
+      return {
+        machine: { name: machine.name, online: true },
+        sessions: (Array.isArray(sessions) ? sessions : []).map((s) => ({
+          machine: machine.name,
+          id: s.id,
+          name: s.name || s.firstMessage || "",
+          agent: s.agentName || s.agent || "",
+          agentName: s.agentName || "",
+          status: s.sessionState?.displayStatus ?? s.status ?? "",
+          needsAction: Boolean(s.needsAction),
+          open: Boolean(s.open),
+          branch: s.branch,
+          lastActivityAt: s.lastActivityAt || s.updatedAt,
+        })),
+        approvals: (Array.isArray(approvals) ? approvals : []).map((a) => ({ ...a, machine: machine.name })),
+      };
+    } catch {
+      return { machine: { name: machine.name, online: false }, sessions: [], approvals: [] };
+    }
+  }));
+  return {
+    machines: results.map((r) => r.machine),
+    sessions: results.flatMap((r) => r.sessions),
+    approvals: results.flatMap((r) => r.approvals),
+  };
+}
+
+export async function runTui({ machines, stdin = process.stdin, stdout = process.stdout }) {
+  const byName = new Map(machines.map((m) => [m.name, m]));
+  let state = initialState();
+  let tick = 0;
+  let previous = [];
+  // Transcripts by session key: raw messages plus the node's history cursor.
+  const histories = new Map();
+  let loadingKey = null;
+
+  const view = () => {
+    const session = selectedSession(state);
+    const key = session ? sessionKey(session) : "";
+    const history = histories.get(key);
+    return { entries: history ? transcriptEntries(history.messages) : [], loading: loadingKey === key && !history };
+  };
+
+  const draw = (full = false) => {
+    const lines = renderFrame(state, view(), { width: stdout.columns || 80, height: stdout.rows || 24, tick });
+    let out = "";
+    lines.forEach((line, i) => { if (full || line !== previous[i]) out += `\x1b[${i + 1};1H${line}\x1b[0m`; });
+    previous = lines;
+    if (out) stdout.write(out);
+  };
+
+  const loadHistory = async (session) => {
+    const key = sessionKey(session);
+    const machine = byName.get(session.machine);
+    const have = histories.get(key);
+    const query = new URLSearchParams({ sessionId: session.id, ...(have ? { have: String(have.count), haveToken: have.hash } : {}) });
+    try {
+      const event = await call(machine, "GET", `/api/session/history?${query}`);
+      const messages = event.mode === "append" && have ? [...have.messages, ...(event.messages ?? [])] : event.messages ?? [];
+      histories.set(key, { messages, count: event.count ?? messages.length, hash: event.historyHash });
+    } catch (error) {
+      state = { ...state, notice: `Couldn't load the transcript: ${error.message}` };
+    } finally {
+      if (loadingKey === key) loadingKey = null;
+    }
+  };
+
+  const refresh = async () => {
+    // Read `state` only after the await: keys pressed meanwhile must survive.
+    const data = await snapshot(machines);
+    state = withData(state, data);
+    const session = selectedSession(state);
+    // Only sessions already open on their machine are followed; opening a closed one is a keypress.
+    if (session?.open) await loadHistory(session);
+    draw();
+  };
+
+  const run = async (effect) => {
+    const machine = effect.session ? byName.get(effect.session.machine) : effect.approval ? byName.get(effect.approval.machine) : null;
+    try {
+      if (effect.type === "open") {
+        loadingKey = sessionKey(effect.session);
+        draw();
+        await loadHistory(effect.session);
+      } else if (effect.type === "prompt") {
+        await call(machine, "POST", "/api/session/prompt", { sessionId: effect.session.id, text: effect.text });
+        state = { ...state, notice: "" };
+      } else if (effect.type === "answer") {
+        await call(machine, "POST", `/api/approvals/${encodeURIComponent(effect.approval.id)}/${effect.approve ? "approve" : "reject"}`, {});
+        state = { ...state, notice: effect.approve ? `Approved ${effect.approval.toolName}.` : `Rejected ${effect.approval.toolName}.` };
+      } else if (effect.type === "stop") {
+        await call(machine, "POST", "/api/session/abort", { sessionId: effect.session.id });
+        state = { ...state, notice: "Stopping…" };
+      }
+    } catch (error) {
+      state = { ...state, notice: error.message };
+    }
+    await refresh();
+  };
+
+  return new Promise((resolve) => {
+    stdout.write("\x1b[?1049h\x1b[?25l\x1b[2J");
+    stdin.setRawMode?.(true);
+    stdin.resume();
+    const poll = setInterval(() => { void refresh(); }, POLL_MS);
+    const spin = setInterval(() => {
+      if (!state.sessions.some(isWorking)) return;
+      tick++;
+      draw();
+    }, SPIN_MS);
+    const onResize = () => draw(true);
+    const quit = () => {
+      clearInterval(poll);
+      clearInterval(spin);
+      stdout.off("resize", onResize);
+      stdin.off("data", onData);
+      stdin.setRawMode?.(false);
+      stdin.pause();
+      stdout.write("\x1b[?25h\x1b[?1049l");
+      resolve();
+    };
+    const onData = (data) => {
+      for (const key of parseKeys(data)) {
+        const before = selectedSession(state);
+        const [next, effect] = reduceKey(state, key);
+        state = next;
+        if (effect?.type === "quit") return quit();
+        if (effect) void run(effect);
+        // Moving onto an open session shows its transcript straight away.
+        const after = selectedSession(state);
+        if (after && after !== before && after.open && !histories.has(sessionKey(after))) {
+          loadingKey = sessionKey(after);
+          void loadHistory(after).then(() => draw());
+        }
+      }
+      draw();
+    };
+    stdin.on("data", onData);
+    stdout.on("resize", onResize);
+    draw(true);
+    void refresh();
+  });
+}

package/bin/tui/model.mjs

@@ -0,0 +1,112 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+// `bivy tui` state and keys, with no I/O: a key press returns the next state and
+// at most one effect for the caller to carry out (answer an approval, send a
+// prompt, open or stop a session, quit).
+
+export function initialState() {
+  return {
+    machines: [],
+    sessions: [],
+    approvals: [],
+    selectedKey: null,
+    focus: "sessions",
+    mode: "normal",
+    filter: "",
+    input: "",
+    scroll: 0,
+    notice: "",
+  };
+}
+
+export const sessionKey = (s) => `${s.machine}/${s.id}`;
+
+const WORKING = new Set(["working", "streaming", "running", "thinking"]);
+export const isWorking = (s) => WORKING.has(String(s?.status ?? "").toLowerCase());
+
+/** The first approval still waiting on this session, if any. */
+export function pendingApproval(state, session) {
+  if (!session) return null;
+  return state.approvals.find((a) => a.machine === session.machine && a.sessionId === session.id && a.status === "pending") ?? null;
+}
+
+const rank = (state, s) => (pendingApproval(state, s) || s.needsAction ? 0 : isWorking(s) ? 1 : 2);
+
+/** Sessions to list: filtered, those waiting on you first, then working, then newest. */
+export function visibleSessions(state) {
+  const needle = state.filter.toLowerCase();
+  return state.sessions
+    .filter((s) => !needle || `${s.name} ${s.agent} ${s.machine} ${s.branch ?? ""}`.toLowerCase().includes(needle))
+    .sort((a, b) => rank(state, a) - rank(state, b) || String(b.lastActivityAt ?? "").localeCompare(String(a.lastActivityAt ?? "")));
+}
+
+export function selectedSession(state) {
+  const list = visibleSessions(state);
+  return list.find((s) => sessionKey(s) === state.selectedKey) ?? list[0] ?? null;
+}
+
+function move(state, delta) {
+  const list = visibleSessions(state);
+  if (!list.length) return state;
+  const current = Math.max(0, list.findIndex((s) => sessionKey(s) === sessionKey(selectedSession(state))));
+  const next = Math.min(list.length - 1, Math.max(0, current + delta));
+  return { ...state, selectedKey: sessionKey(list[next]), scroll: 0 };
+}
+
+/** Replace what the machines reported, keeping the selection on the same session. */
+export function withData(state, { machines, sessions, approvals }) {
+  const next = { ...state, machines, sessions, approvals };
+  const selected = selectedSession(next);
+  return { ...next, selectedKey: selected ? sessionKey(selected) : null };
+}
+
+/** Handle one key. Returns `[state, effect | null]`. */
+export function reduceKey(state, key) {
+  if (key === "ctrl-c") return [state, { type: "quit" }];
+  const session = selectedSession(state);
+
+  if (state.mode === "help") return [{ ...state, mode: "normal" }, null];
+
+  if (state.mode === "filter" || state.mode === "prompt") {
+    if (key === "esc") return [{ ...state, mode: "normal", input: "", ...(state.mode === "filter" ? { filter: "" } : {}) }, null];
+    if (key === "enter") {
+      if (state.mode === "filter") return [{ ...state, mode: "normal", filter: state.input, input: "" }, null];
+      const text = state.input.trim();
+      const next = { ...state, mode: "normal", input: "", scroll: 0 };
+      return [next, text && session ? { type: "prompt", session, text } : null];
+    }
+    if (key === "backspace") {
+      const input = [...state.input].slice(0, -1).join("");
+      return [{ ...state, input, ...(state.mode === "filter" ? { filter: input } : {}) }, null];
+    }
+    if ([...key].length === 1 || key === "space") {
+      const input = state.input + (key === "space" ? " " : key);
+      return [{ ...state, input, ...(state.mode === "filter" ? { filter: input } : {}) }, null];
+    }
+    return [state, null];
+  }
+
+  const inTranscript = state.focus === "transcript";
+  switch (key) {
+    case "q": return [state, { type: "quit" }];
+    case "?": return [{ ...state, mode: "help" }, null];
+    case "tab": case "left": case "right": case "h": case "l":
+      return [{ ...state, focus: key === "h" || key === "left" ? "sessions" : key === "l" || key === "right" ? "transcript" : inTranscript ? "sessions" : "transcript" }, null];
+    case "j": case "down": return [inTranscript ? { ...state, scroll: Math.max(0, state.scroll - 1) } : move(state, 1), null];
+    case "k": case "up": return [inTranscript ? { ...state, scroll: state.scroll + 1 } : move(state, -1), null];
+    case "pagedown": case "ctrl-d": return [inTranscript ? { ...state, scroll: Math.max(0, state.scroll - 10) } : move(state, 10), null];
+    case "pageup": case "ctrl-u": return [inTranscript ? { ...state, scroll: state.scroll + 10 } : move(state, -10), null];
+    case "g": return [inTranscript ? { ...state, scroll: Number.MAX_SAFE_INTEGER } : move(state, -Infinity), null];
+    case "G": return [inTranscript ? { ...state, scroll: 0 } : move(state, Infinity), null];
+    case "/": return [{ ...state, mode: "filter", input: state.filter }, null];
+    case "esc": return [{ ...state, filter: "", notice: "" }, null];
+    case "enter": return [{ ...state, focus: "transcript" }, session && !session.open ? { type: "open", session } : null];
+    case "i": case "c": return session ? [{ ...state, mode: "prompt", input: "", focus: "transcript" }, null] : [state, null];
+    case "a": case "r": {
+      const approval = pendingApproval(state, session);
+      return approval ? [state, { type: "answer", approval, approve: key === "a" }] : [{ ...state, notice: "Nothing to approve here." }, null];
+    }
+    case "x": return session && isWorking(session) ? [state, { type: "stop", session }] : [state, null];
+    default: return [state, null];
+  }
+}

package/bin/tui/render.mjs

@@ -0,0 +1,164 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+// `bivy tui` frame: state in, exactly `height` lines of exactly `width` cells
+// out. It uses the terminal's own 16 colors, so it follows the terminal theme.
+
+import { fit, truncate, width as cells, wrap } from "./text.mjs";
+import { isWorking, pendingApproval, selectedSession, visibleSessions } from "./model.mjs";
+
+const esc = (code) => (text) => `\x1b[${code}m${text}\x1b[0m`;
+const bold = esc("1");
+const dim = esc("2");
+const inverse = esc("7");
+const red = esc("31");
+const green = esc("32");
+const yellow = esc("33");
+const blue = esc("34");
+const cyan = esc("36");
+
+const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+/** Status glyphs; each also has a word in the session header for anyone not reading color. */
+function glyph(state, session, tick) {
+  if (pendingApproval(state, session) || session.needsAction) return yellow("!");
+  if (isWorking(session)) return cyan(SPINNER[tick % SPINNER.length]);
+  if (/error|failed/i.test(session.status ?? "")) return red("✕");
+  // Narrow in every monospace font (unlike ● and ○), so the name never shifts.
+  return session.open ? green("•") : dim("·");
+}
+
+function statusWord(state, session) {
+  if (pendingApproval(state, session) || session.needsAction) return yellow("waiting on you");
+  if (isWorking(session)) return cyan("working");
+  return dim(session.open ? String(session.status || "idle") : "closed");
+}
+
+export function ago(iso, now) {
+  const ms = now - Date.parse(iso ?? "");
+  if (!Number.isFinite(ms)) return "";
+  const m = Math.round(ms / 60000);
+  if (m < 1) return "now";
+  if (m < 60) return `${m}m`;
+  const h = Math.round(m / 60);
+  return h < 48 ? `${h}h` : `${Math.round(h / 24)}d`;
+}
+
+/** A rounded box `w` wide and `h` tall around `body` lines, titled; bright border when focused. */
+function box(title, body, w, h, focused) {
+  const paint = focused ? green : (text) => text;
+  const label = title ? ` ${truncate(title, w - 6)} ` : "";
+  const top = paint("╭─") + (focused ? bold(label) : label) + paint(`${"─".repeat(Math.max(0, w - 3 - cells(label)))}╮`);
+  const rows = [];
+  for (let i = 0; i < h - 2; i++) rows.push(paint("│") + fit(body[i] ?? "", w - 2) + paint("│"));
+  return [top, ...rows, paint(`╰${"─".repeat(w - 2)}╯`)];
+}
+
+function sessionRows(state, w, h, now, tick) {
+  const list = visibleSessions(state);
+  if (!list.length) return [dim(state.filter ? " No sessions match." : " No sessions yet. Start one with 'bivy run'.")];
+  const selected = selectedSession(state);
+  const index = Math.max(0, list.indexOf(selected));
+  const start = Math.max(0, Math.min(index - Math.floor(h / 2), list.length - h));
+  const multi = state.machines.length > 1;
+  return list.slice(start, start + h).map((s) => {
+    const right = `${multi ? `${s.machine} ` : ""}${ago(s.lastActivityAt, now)}`;
+    const name = fit(` ${glyph(state, s, tick)} ${s.name || s.id}`, Math.max(4, w - cells(right) - 2));
+    const row = `${name} ${dim(right)} `;
+    return s === selected ? (state.focus === "sessions" ? inverse(fit(row, w)) : bold(fit(row, w))) : row;
+  });
+}
+
+function transcriptLines(entries, agentName, w) {
+  const lines = [];
+  for (const entry of entries) {
+    if (entry.role === "tool") { lines.push(dim(`  ▸ ${truncate(entry.text, w - 4)}`)); continue; }
+    lines.push("");
+    lines.push(entry.role === "user" ? bold(blue("you")) : bold(green(agentName)));
+    for (const line of wrap(entry.text, w - 2)) lines.push(` ${line}`);
+  }
+  return lines;
+}
+
+function approvalCard(approval, w) {
+  const head = `${yellow(bold("! Approve"))} ${bold(approval.toolName)}${approval.risk ? dim(` (${approval.risk})`) : ""}`;
+  const reason = wrap(String(approval.reason ?? ""), w - 4).slice(0, 3).map((l) => `  ${l}`);
+  return ["", head, ...reason, `  ${bold("a")} approve   ${bold("r")} reject`];
+}
+
+function detailRows(state, view, w, h) {
+  const session = selectedSession(state);
+  if (!session) return [];
+  const header = [session.agent, state.machines.length > 1 ? session.machine : "", session.branch].filter(Boolean).join(" · ");
+  const top = [`${dim(header)}${header ? dim(" · ") : ""}${statusWord(state, session)}`];
+  const approval = pendingApproval(state, session);
+  const bottom = approval ? approvalCard(approval, w) : [];
+  if (state.mode === "prompt") bottom.push("", `${blue("›")} ${truncate(state.input, w - 4)}${inverse(" ")}`);
+  const room = Math.max(0, h - top.length - bottom.length);
+  let body;
+  if (!session.open && !view.entries?.length) {
+    body = ["", dim(" Closed. Press enter to open it.")];
+  } else if (view.loading) {
+    body = ["", dim(" Loading…")];
+  } else {
+    const lines = transcriptLines(view.entries ?? [], session.agentName || session.agent || "agent", w);
+    const scroll = Math.min(state.scroll, Math.max(0, lines.length - room));
+    body = lines.slice(Math.max(0, lines.length - room - scroll), lines.length - scroll);
+  }
+  return [...top, ...body, ...Array(Math.max(0, room - body.length)).fill(""), ...bottom].slice(0, h);
+}
+
+const HELP = [
+  ["j/k ↑/↓", "move, or scroll the transcript"],
+  ["tab h/l", "switch pane"],
+  ["enter", "open the session"],
+  ["i", "message the agent"],
+  ["a / r", "approve / reject what it's asking"],
+  ["x", "stop the current turn"],
+  ["/", "filter sessions"],
+  ["g / G", "top / bottom"],
+  ["q", "quit"],
+];
+
+function keyBar(state) {
+  if (state.mode === "filter") return `${blue("/")}${state.input}${inverse(" ")}  ${dim("enter keep · esc clear")}`;
+  if (state.mode === "prompt") return dim("enter send · esc cancel");
+  if (state.notice) return yellow(state.notice);
+  const keys = [["enter", "open"], ["i", "message"], ["a/r", "approve/reject"], ["x", "stop"], ["/", "filter"], ["?", "help"], ["q", "quit"]];
+  return keys.map(([k, label]) => `${bold(k)} ${dim(label)}`).join("  ");
+}
+
+/** The whole screen as `height` lines. `view` is the selected session's transcript: `{ entries, loading }`. */
+export function renderFrame(state, view, { width, height, now = Date.now(), tick = 0 }) {
+  const waiting = state.sessions.filter((s) => pendingApproval(state, s) || s.needsAction).length;
+  const offline = state.machines.filter((m) => !m.online).map((m) => m.name);
+  const summary = [
+    `${state.machines.length} machine${state.machines.length === 1 ? "" : "s"}`,
+    `${state.sessions.length} session${state.sessions.length === 1 ? "" : "s"}`,
+    waiting ? yellow(`${waiting} waiting on you`) : "",
+    offline.length ? red(`${offline.join(", ")} offline`) : "",
+  ].filter(Boolean).join(dim(" · "));
+  const title = fit(`${inverse(bold(" bivy "))} ${summary}`, width);
+
+  const left = Math.max(24, Math.min(48, Math.floor(width * 0.36)));
+  const right = width - left;
+  const paneHeight = Math.max(3, height - 2);
+  const sessionsTitle = `Sessions${state.filter ? ` /${state.filter}` : ""}`;
+  const leftBox = box(sessionsTitle, sessionRows(state, left - 2, paneHeight - 2, now, tick), left, paneHeight, state.focus === "sessions");
+  const selected = selectedSession(state);
+  const rightBox = box(selected ? selected.name || selected.id : "", detailRows(state, view, right - 2, paneHeight - 2), right, paneHeight, state.focus === "transcript");
+
+  let lines = [title, ...leftBox.map((l, i) => l + rightBox[i]), fit(` ${keyBar(state)}`, width)];
+  if (state.mode === "help") {
+    const w = Math.min(width - 4, 52);
+    const body = HELP.map(([k, label]) => ` ${bold(k.padEnd(9))} ${label}`);
+    const overlay = box("Keys", body, w, body.length + 2, true);
+    const top = Math.max(1, Math.floor((height - overlay.length) / 2));
+    const x = Math.floor((width - w) / 2);
+    lines = lines.map((line, i) => {
+      const o = overlay[i - top];
+      return o ? fit(" ".repeat(x), x) + o + " ".repeat(Math.max(0, width - x - w)) : line;
+    });
+  }
+  return lines.slice(0, height);
+}
+

package/bin/tui/text.mjs

@@ -0,0 +1,72 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+// Terminal cell arithmetic for `bivy tui`: visible width of styled text,
+// truncating, padding and wrapping it without splitting an escape sequence.
+
+const ANSI = /\x1b\[[0-9;]*m/g;
+// Wide (two-cell) characters: CJK, Hangul, fullwidth forms and most emoji.
+const WIDE = /[\u1100-\u115f\u2e80-\u303e\u3041-\u33ff\u3400-\u4dbf\u4e00-\u9fff\ua000-\ua4cf\uac00-\ud7a3\uf900-\ufaff\ufe30-\ufe4f\uff00-\uff60\uffe0-\uffe6\u{1f300}-\u{1f64f}\u{1f900}-\u{1f9ff}\u{20000}-\u{3fffd}]/u;
+// Zero-width: combining marks, variation selectors, joiners.
+const ZERO = /[\p{Mn}\p{Cf}]/u;
+
+export const stripAnsi = (text) => String(text).replace(ANSI, "");
+
+function charWidth(ch) {
+  if (ZERO.test(ch)) return 0;
+  return WIDE.test(ch) ? 2 : 1;
+}
+
+export function width(text) {
+  let w = 0;
+  for (const ch of stripAnsi(text)) w += charWidth(ch);
+  return w;
+}
+
+/** Split styled text into [escape | character] tokens. */
+function tokens(text) {
+  return String(text).match(/\x1b\[[0-9;]*m|[\s\S]/gu) ?? [];
+}
+
+/** Cut to at most `max` cells, ending in "…" when anything was dropped. */
+export function truncate(text, max) {
+  if (max <= 0) return "";
+  if (width(text) <= max) return text;
+  let out = "";
+  let w = 0;
+  for (const token of tokens(text)) {
+    if (token.startsWith("\x1b")) { out += token; continue; }
+    const cw = charWidth(token);
+    if (w + cw > max - 1) break;
+    out += token;
+    w += cw;
+  }
+  return `${out}…\x1b[0m`;
+}
+
+/** Exactly `size` cells: truncated, or padded with spaces. */
+export function fit(text, size) {
+  const cut = truncate(text, size);
+  return cut + " ".repeat(Math.max(0, size - width(cut)));
+}
+
+/** Word-wrap plain text to `max` cells per line, hard-breaking long words. */
+export function wrap(text, max) {
+  const lines = [];
+  for (const paragraph of String(text).replace(/\t/g, "  ").split("\n")) {
+    let line = "";
+    for (const word of paragraph.split(/(\s+)/)) {
+      if (!word) continue;
+      if (width(line + word) <= max) { line += word; continue; }
+      if (line.trim()) lines.push(line.trimEnd());
+      line = /^\s+$/.test(word) ? "" : word;
+      while (width(line) > max) {
+        let head = "";
+        for (const ch of line) { if (width(head + ch) > max) break; head += ch; }
+        lines.push(head);
+        line = line.slice(head.length);
+      }
+    }
+    lines.push(line.trimEnd());
+  }
+  return lines;
+}