@bivy/bivy 0.20.1-staging.6 → 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(
@@ -2554,6 +2580,30 @@ async function cmdSuggest(args = []) {
   console.log(c.green("Suggested in the chat. The user can start it in one tap."));
 }
 
+// `bivy title "<title>" [--session <id>]` — rename the session the agent runs in.
+async function cmdTitle(args = []) {
+  const usage = 'Usage: bivy title "<title>" [--session <id>] [--json]';
+  if (args.includes("-h") || args.includes("--help")) {
+    console.log(`${usage}\n\nRename this session in the user's session list. Use a short title that says what the work is, when the first message made a poor title or the work changed direction. --json prints {"ok","title"}.`);
+    return;
+  }
+  const json = wantsJson(args);
+  const fail = (error) => cliError(error, { json, paint: c.red });
+  const sessionFlag = args.indexOf("--session");
+  const title = args.filter((a, i) => !a.startsWith("-") && !(sessionFlag >= 0 && i === sessionFlag + 1)).join(" ").trim();
+  const sessionId = resolveAttachSessionId({ sessionFlag: sessionFlag >= 0 ? args[sessionFlag + 1] : undefined, env: process.env });
+  if (!title) return fail({ code: "usage", message: usage, exit: EXIT.usage });
+  if (!sessionId) return fail({ code: "no_session", message: "No session id.", hint: "Run inside an agent session ($BIVY_SESSION_ID) or pass --session <id>.", next: "bivy sessions --json", exit: EXIT.usage });
+  const config = loadConfig();
+  if (!(await ensureNodeRunning(config))) return fail({ code: "node_unreachable", message: `Could not reach the Bivy node at ${url(config)}.`, next: "bivy status", exit: EXIT.unavailable });
+  const res = await sessionPost(config, sessionId, "title", { title }).catch((error) => error);
+  if (res instanceof Error) return fail({ code: "node_unreachable", message: `Could not reach the Bivy node: ${res.message}`, next: "bivy status", exit: EXIT.unavailable });
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok) return fail(sessionHttpError("Title", res.status, body));
+  if (json) { console.log(JSON.stringify(body)); return; }
+  console.log(c.green(`Renamed this session to "${body.title}".`));
+}
+
 // Flags shared by the session commands: `--name value` pairs and bare switches,
 // with every other word collected as positional text.
 function parseSessionArgs(args, valueFlags) {
@@ -5290,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.
@@ -6204,6 +6261,9 @@ An agent's own --help passes through, e.g. 'bivy run claude --help'.`);
     case "suggest":
       await cmdSuggest(args);
       break;
+    case "title":
+      await cmdTitle(args);
+      break;
     case "notify":
       await cmdNotify(args);
       break;
@@ -6387,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

@@ -48,6 +48,8 @@ export const COMMANDS = [
     tools: [{ name: "notify_user", description: "Send the user a message: a card in the chat, and a push to their phone when nobody has the app open (the push names the session, not the text). Use it when long work finishes, you are blocked, or something needs their attention. At most one push a minute per session.", input: { message: { type: "string", description: "What to tell the user.", required: true }, urgent: { type: "boolean", description: "Push even while the user has the app open." } }, argv: ["notify", { arg: "message" }, { when: "urgent", flag: "--urgent" }] }] },
   { name: "ask", group: "session", scope: "session", json: true, usage: 'ask "<question>" [--option A --option B] [--async]', summary: "Ask the user a question and wait for the answer", subcommands: ["status", "wait"],
     tools: [{ name: "ask_user", description: "Ask the user a question in the chat and wait for their answer (their phone gets a push). Offer 2-8 options, or none for a free-text answer; they can always write their own. Returns {status, answer}: status is answered, dismissed (decide yourself) or expired.", input: { question: { type: "string", description: "The question.", required: true }, options: { type: "array", items: { type: "string" }, description: "Choices to pick from (2-8)." }, multiple: { type: "boolean", description: "Allow several choices." }, header: { type: "string", description: "A short label for the card." }, timeout_seconds: { type: "number", description: "How long to wait (default 600)." } }, argv: ["ask", { arg: "question" }, { flag: "--option", from: "options" }, { when: "multiple", flag: "--multi" }, { flag: "--header", from: "header" }, { flag: "--timeout", from: "timeout_seconds" }] }] },
+  { name: "title", group: "session", scope: "session", json: true, usage: 'title "<title>"', summary: "Rename this session",
+    tools: [{ name: "set_session_title", description: "Rename this session in the user's session list. Use a short title (under 60 characters) that says what the work is, when the first message made a poor title or the work changed direction.", input: { title: { type: "string", description: "The new title.", required: true } }, argv: ["title", { arg: "title" }] }] },
   { name: "suggest", group: "session", scope: "session", json: true, usage: 'suggest "<task>" [--title "label"] [--run here|subagents|new]', summary: "Propose a task the user can start in one tap",
     tools: [{ name: "suggest_task", description: "Propose a next step the user can start in one tap: in this session, through your sub-agents, or in a parallel session with its own copy of the project. Write the task as a complete instruction with paths relative to the project root. Post one per idea instead of listing them.", input: { task: { type: "string", description: "The complete instruction.", required: true }, title: { type: "string", description: "A short label for the card." }, run: { type: "string", enum: ["here", "subagents", "new"], description: "Where you recommend running it: here (builds on this conversation), subagents (independent tasks you can split across your own sub-agents; only if you have them), or new (bigger independent work in its own session). Defaults: here for one card, new for several." } }, argv: ["suggest", { arg: "task" }, { flag: "--title", from: "title" }, { flag: "--run", from: "run" }] }] },
   { name: "app", group: "session", scope: "session", json: true, usage: "app <publish|shot|present|share|run|…>", summary: "Live previews: publish a web/terminal/desktop app, screenshot it, present it", subcommands: ["publish", "list", "remove", "shot", "present", "share", "notes", "run", "click", "type", "key", "scroll", "drag", "move", "menu"],
@@ -63,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/guides/talk-to-the-user.md

@@ -41,6 +41,13 @@ instead of a bulleted list.
 | `subagents` | Independent tasks you can split across your own sub-agents and report back on. Only if you have sub-agents. |
 | `new` | Bigger independent work the user will want to follow, review or merge on its own. Default for several cards. |
 
+## Name the session: title
+
+    bivy title "Fix login redirect loop"
+
+The session list shows a title taken from the first message. When that doesn't
+say what the work is, or the work changes direction, rename it. Keep it short.
+
 ## Is anyone there?
 
 `bivy context --json` reports `userConnected` (some device has the app open) and

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);
+}
+