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

package/bin/access-view.mjs

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+// Terminal views of the node's access report (src/access.ts): the full
+// `bivy access` screen and the one-line summary `bivy status` shows.
+
+const REACH_WORD = ["", "on your tailnet", "from anywhere"];
+
+/** "Tailscale + Bivy hosted", or "This machine only". */
+export function activeLabel(report) {
+  const on = report.setups.filter((s) => s.active && s.id !== "local");
+  return on.length ? on.map((s) => s.label).join(" + ") : "This machine only";
+}
+
+function labelOf(report, id) {
+  return report.setups.find((s) => s.id === id)?.label ?? id;
+}
+
+/** `access: Tailscale — next: Bivy hosted` for `bivy status`. */
+export function accessLine(report) {
+  const next = report.next.filter((n) => n.id !== "server").map((n) => labelOf(report, n.id));
+  return `${activeLabel(report)}${next.length ? ` — next: ${next.join(" or ")} ('bivy access')` : ""}`;
+}
+
+/** The `bivy access` screen as lines; `paint` supplies colors. */
+export function accessScreen(report, paint) {
+  const lines = [`${paint.bold("Access:")} ${activeLabel(report)}`];
+  if (report.tailscaleUrl) lines.push(`  ${paint.dim("tailnet")}  ${report.tailscaleUrl}`);
+  if (report.controlPlaneUrl) lines.push(`  ${paint.dim("app")}      ${report.controlPlaneUrl}`);
+  lines.push("");
+  for (const feature of report.features) {
+    const reach = report.reach[feature.id];
+    lines.push(`  ${reach ? paint.green("✓") : paint.dim("✗")} ${feature.label}${reach ? paint.dim(` ${REACH_WORD[reach]}`.trimEnd()) : ""}`);
+  }
+  if (report.next.length) {
+    lines.push("", paint.bold("Next:"));
+    for (const step of report.next) {
+      const setup = report.setups.find((s) => s.id === step.id);
+      lines.push(`  ${paint.cyan((setup?.command ?? "").padEnd(26))} ${setup?.label}`, `  ${" ".repeat(26)} ${paint.dim(`adds ${step.addsText}`)}`);
+    }
+  }
+  lines.push("", paint.dim("Setups stack: adding one never takes away another. 'bivy access local' turns remote access off."));
+  return lines;
+}

package/bin/bivy.mjs

@@ -40,9 +40,10 @@ import { nativeResumeRef, resolveSessionsLimit, truncateSavedSessions } from "./
 import { renderManagedBlock, upsertManagedBlock, removeManagedBlock, rcFileForShell } from "./shim-path.mjs";
 import { removeInstallAndState } from "./uninstall-paths.mjs";
 import { findAvailablePort, reconcilePort } from "./port-picker.mjs";
+import { accessLine, accessScreen } from "./access-view.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 +78,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 +2135,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(
@@ -4501,6 +4528,8 @@ async function cmdTokenSetup() {
 }
 
 async function cmdSetup(args = []) {
+  // Set by the access question; `bivy tailscale` runs once the node is up.
+  let wantTailscale = false;
   if (args.includes("-h") || args.includes("--help")) {
     console.log("Usage: bivy setup\n\nFirst-run wizard: agent choice, model login, remote access + sign-in, and background service. Workspace and port get safe defaults. Re-run later to change the default agent or remote access.");
     return;
@@ -4608,18 +4637,22 @@ async function cmdSetup(args = []) {
     // (BIVY_CONTROL_PLANE_URL / BIVY_RELAY_URL then pre-fill the URL prompts below).
     const nodeClaimCode = process.env.BIVY_NODE_CLAIM_CODE?.trim();
     const selfHostEnv = !nodeClaimCode && Boolean((process.env.BIVY_CONTROL_PLANE_URL || "").trim() || (process.env.BIVY_RELAY_URL || "").trim());
+    // Tailscale is offered only where it's installed; it needs no account.
+    const tailscaleInstalled = runTailscale(["version"]) !== null;
     const syncChoice = nodeClaimCode ? "h" : await askChoice(
-      "Remote access",
+      "How will you reach this machine?",
       [
-        { key: "h", label: "hosted (recommended — sign in with GitHub or email; nothing caps your local usage)" },
-        { key: "s", label: "self-hosted (your own control plane + relay)" },
-        { key: "l", label: "local only for now (terminal CLI only; run 'bivy relay:setup' later)" },
+        { key: "h", label: "Bivy hosted (recommended — sign in with GitHub or email; every machine, from anywhere)" },
+        ...(tailscaleInstalled ? [{ key: "t", label: "Tailscale (your devices over your tailnet; no account, nothing in between)" }] : []),
+        { key: "s", label: "your own server (a Bivy server you run)" },
+        { key: "l", label: "this machine only for now (add more any time with 'bivy access')" },
       ],
       selfHostEnv ? "s" : "h",
     );
+    wantTailscale = syncChoice === "t";
     const relayArgs = [];
-    if (syncChoice === "l") {
-      console.log(c.dim("\nSkipping remote access. Enable it any time with 'bivy relay:setup'."));
+    if (syncChoice === "l" || syncChoice === "t") {
+      console.log(c.dim(`\n${syncChoice === "t" ? "Tailscale is turned on once the node is running." : "Skipping remote access."} 'bivy access' shows every option later.`));
     }
     if (syncChoice === "s") {
       const endpoints = await getHostedEndpoints();
@@ -4629,7 +4662,7 @@ async function cmdSetup(args = []) {
       if (relayWs.trim()) relayArgs.push("--relay", relayWs.trim());
     }
 
-    if (syncChoice !== "l") {
+    if (syncChoice !== "l" && syncChoice !== "t") {
       if (!nodeClaimCode) {
         const loginChoice = await askChoice(
           "Remote login",
@@ -4678,7 +4711,7 @@ async function cmdSetup(args = []) {
       setupSession = consumeSetupSession();
     }
   } else {
-    console.log(c.dim("\nRemote access already configured. Re-run 'bivy relay:setup' to change sync or sign-in."));
+    console.log(c.dim("\nRemote access already configured. 'bivy access' shows it and the other options."));
   }
 
   // GitHub App — connect it from the web app (Settings → GitHub App) or with
@@ -4758,6 +4791,7 @@ async function cmdSetup(args = []) {
     ? Boolean(liveReadiness?.credential?.ok ?? hasModelConfig(finalConfig))
     : agentAuthReady;
   const repoReady = Boolean(liveReadiness?.repository?.ok);
+  if (wantTailscale) await cmdTailscale(["on"]).catch((error) => console.log(c.yellow(`Tailscale setup didn't finish: ${error?.message || error}. Run 'bivy access tailscale' to retry.`)));
   console.log(c.bold(c.green("\n  ✓ Node running. Check first-task readiness below.\n")));
   console.log(`  ${c.green("✓")} node reachable at ${url(finalConfig)}`);
   console.log(`  ${agentReady ? c.green("✓") : c.yellow("!")} runtime ${agentReady ? `${setupAgent?.label || "Pi"} available` : "not installed — run 'bivy agents:install'"}`);
@@ -4766,7 +4800,7 @@ async function cmdSetup(args = []) {
   const ghReady = githubConnected(finalConfig);
   console.log(`  ${ghReady ? c.green("✓") : c.dim("○")} GitHub ${ghReady ? "connected — your repos will list in the app" : c.dim("optional — connect later in the app under Settings → GitHub App")}`);
   console.log(`  ${agentReady && modelReady && repoReady ? c.green("✓") : c.yellow("!")} first task ${agentReady && modelReady && repoReady ? "ready to try" : "blocked by the stage above"}`);
-  console.log(`  ${fs.existsSync(relayConfigPath) ? c.green("✓") : c.yellow("!")} remote ${fs.existsSync(relayConfigPath) ? "configured" : "not configured — run 'bivy relay:setup'"}\n`);
+  console.log(`  ${fs.existsSync(relayConfigPath) || fs.existsSync(tailscaleConfigPath) ? c.green("✓") : c.dim("○")} access ${fs.existsSync(relayConfigPath) || fs.existsSync(tailscaleConfigPath) ? "set up — 'bivy access' shows what it gives you" : "this machine only — 'bivy access' shows the options"}\n`);
   // Get the user into the product immediately; terminal commands are the
   // fallback/next-step checklist after the remote app has been opened or linked.
   await finishSetupRemote(finalConfig, setupSession);
@@ -4953,8 +4987,10 @@ async function cmdStatus(args = []) {
   const relay = loadRelayConfig();
   const relaySt = status?.relay;
   const relayConfigured = Boolean(relaySt?.configured || relay);
+  const access = reachable ? await fetchAccess(config).catch(() => null) : null;
+  if (access) console.log(`  access:    ${accessLine(access)}`);
   if (!relayConfigured) {
-    console.log(`  remote:    ${c.dim("local only")}  ${c.dim("('bivy relay:setup' to enable remote access)")}`);
+    if (!access) console.log(`  remote:    ${c.dim("this machine only")}  ${c.dim("('bivy access' to see the options)")}`);
   } else {
     // The live link state is only knowable when the node is running; if it's
     // down we can say it's configured but not whether it's currently connected.
@@ -5149,7 +5185,7 @@ async function cmdDoctor(args = []) {
   const relayApp = status?.relay?.controlPlaneUrl;
   const relayErr = status?.relay?.lastError;
   const relayLine = !relayConfigured
-    ? c.dim("local only — 'bivy relay:setup' to enable")
+    ? c.dim("this machine only — 'bivy access' to see the options")
     : relayConnected
       ? c.green("relay connected") + (relayApp ? c.dim(`  ${relayApp}`) : "")
       : c.yellow("configured, not connected") + (relayErr ? c.dim(`  (${relayErr})`) : "");
@@ -5314,6 +5350,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.
@@ -5782,7 +5825,7 @@ async function cmdTailscale(args = []) {
     process.exitCode = EXIT.unavailable;
     return;
   }
-  const { running, hostname } = parseTailscaleStatus(status.stdout);
+  const { running, hostname, owner } = parseTailscaleStatus(status.stdout);
   if (!running || !hostname) {
     console.log(`${c.yellow("Tailscale isn't connected.")} Sign in with ${c.cyan("sudo tailscale up")}, then run ${c.cyan("bivy tailscale")} again.`);
     process.exitCode = EXIT.unavailable;
@@ -5795,7 +5838,7 @@ async function cmdTailscale(args = []) {
     process.exitCode = EXIT.conflict;
     return;
   }
-  fs.writeFileSync(tailscaleConfigPath, `${JSON.stringify({ port, hostname }, null, 2)}\n`, { mode: 0o600 });
+  fs.writeFileSync(tailscaleConfigPath, `${JSON.stringify({ port, hostname, ...(owner ? { owner } : {}) }, null, 2)}\n`, { mode: 0o600 });
   const reload = await localApi(config, "/api/direct/reload", { method: "POST", body: "{}" });
   const served = runTailscale(serveOnArgs(port));
   if (!served?.ok) {
@@ -5808,12 +5851,83 @@ async function cmdTailscale(args = []) {
     return;
   }
   console.log(c.bold(c.green(`\n  Bivy is on https://${hostname}\n`)));
-  console.log(c.dim("  Only devices on your tailnet can reach it. Pair each one once with a link from 'bivy tailscale pair'."));
+  console.log(c.dim(owner
+    ? `  Only devices on your tailnet can reach it. Yours (signed in as ${owner}) are let in without pairing;\n  anyone else's pairs once with a link from 'bivy tailscale pair'.`
+    : "  Only devices on your tailnet can reach it. This machine is tagged, so each device pairs once with a link from 'bivy tailscale pair'."));
   if (!reload?.webApp) console.log(c.yellow("  This install has no built web app, so the address serves the API only. Run 'pnpm run build:web' in a source checkout."));
   console.log("");
+  if (owner) {
+    console.log(`Open ${c.cyan(`https://${hostname}`)} on any of your devices.\n`);
+    return;
+  }
   await printPairLink(config);
 }
 
+async function fetchAccess(config) {
+  return localApi(config, "/api/access/get", { method: "POST", body: "{}" });
+}
+
+// `bivy access` — how this machine can be reached (this machine only,
+// Tailscale, Bivy hosted, your own server), what that gives you, and the next
+// step. The node owns the table (src/access.ts); this only renders and routes.
+async function cmdAccess(args = []) {
+  const [verb, target] = args.filter((a) => !a.startsWith("-"));
+  if (args.includes("-h") || args.includes("--help") || (verb && !["local", "tailscale", "hosted", "server"].includes(verb))) {
+    console.log(`Usage: bivy access [--json]
+       bivy access tailscale              reach this machine from your devices over Tailscale
+       bivy access hosted                 sign in to Bivy hosted: every machine, from anywhere
+       bivy access server <url> [--relay <wss-url>]   the same, through your own server
+       bivy access local                  turn remote access off
+
+Setups stack: Tailscale can stay on alongside hosted or your own server.`);
+    if (verb && !["local", "tailscale", "hosted", "server"].includes(verb)) 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 report = await fetchAccess(config);
+
+  if (!verb) {
+    if (wantsJson(args)) { console.log(JSON.stringify(report, null, 2)); return; }
+    console.log(`\n${accessScreen(report, c).join("\n")}\n`);
+    return;
+  }
+  if (verb === "tailscale") return cmdTailscale(["on"]);
+  if (verb === "hosted" || verb === "server") {
+    const linked = report.setups.find((s) => s.active && (s.id === "hosted" || s.id === "server"));
+    if (linked && linked.id === verb && verb === "hosted") {
+      console.log(`Already on ${linked.label}${report.controlPlaneUrl ? ` (${report.controlPlaneUrl})` : ""}.`);
+      return;
+    }
+    if (linked) console.log(c.yellow(`This machine is on ${linked.label}${report.controlPlaneUrl ? ` (${report.controlPlaneUrl})` : ""}. Switching keeps everything on this machine; your devices sign in again at the new address.`));
+    if (verb === "hosted") return cmdRelaySetup([]);
+    if (!target) {
+      console.log(`Usage: bivy access server <url> [--relay <wss-url>]\n\nThe address of your Bivy server, e.g. https://bivy.example.com. Set one up with docs/self-host-quickstart.md.`);
+      process.exitCode = EXIT.usage;
+      return;
+    }
+    let appUrl;
+    try { appUrl = new URL(/^https?:\/\//.test(target) ? target : `https://${target}`); } catch { appUrl = null; }
+    if (!appUrl) { console.error(c.red(`Not a URL: ${target}`)); process.exitCode = EXIT.usage; return; }
+    // Bivy's server installs serve the relay at /relay on the app's own domain.
+    const relayUrl = argValue(args, "relay") || `${appUrl.protocol === "http:" ? "ws" : "wss"}://${appUrl.host}/relay`;
+    return cmdRelaySetup(["--control-plane", appUrl.origin, "--relay", relayUrl]);
+  }
+  // local: turn off every remote setup that is on.
+  const on = report.setups.filter((s) => s.active && s.id !== "local");
+  if (!on.length) { console.log("Already this machine only."); return; }
+  const rl = createPrompter();
+  const yes = await rl.askYesNo(`Turn off ${on.map((s) => s.label).join(" and ")}? Sessions and credentials on this machine stay.`, false);
+  rl.close();
+  if (!yes) return;
+  if (on.some((s) => s.id === "tailscale")) await cmdTailscale(["off"]);
+  if (on.some((s) => s.id === "hosted" || s.id === "server")) await cmdAccountLogout([]);
+}
+
 function printUninstallHelp() {
   console.log(`
 ${c.bold("bivy uninstall")} — remove Bivy and all its data from this machine
@@ -6414,9 +6528,15 @@ 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;
+    case "access":
+      await cmdAccess(args);
+      break;
     case "relay:setup":
       await cmdRelaySetup(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" },
@@ -105,6 +106,7 @@ export const COMMANDS = [
   { name: "token", group: "node", scope: "node", usage: "token", summary: "Print a device token for this node" },
   { name: "open", group: "node", scope: "node", usage: "open", summary: "Open the remote web app" },
   { name: "link", group: "node", scope: "node", usage: "link", summary: "Show a web app link as a QR code in the terminal" },
+  { name: "access", group: "node", scope: "node", json: true, usage: "access [local|tailscale|hosted|server <url>]", summary: "How this machine can be reached, what that gives you, and the next step", subcommands: ["local", "tailscale", "hosted", "server"] },
   { name: "tailscale", group: "node", scope: "node", usage: "tailscale [on|pair|status|devices|revoke|off]", summary: "Reach this machine over Tailscale, with no server in between", subcommands: ["on", "pair", "status", "devices", "revoke", "off"] },
   { name: "relay:setup", group: "node", scope: "node", usage: "relay:setup", summary: "Enable secure remote web app access" },
   { name: "uninstall", group: "node", scope: "node", usage: "uninstall [--keep-sessions] [--dry-run]", summary: "Remove Bivy and all its data" },

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/tailscale.mjs

@@ -7,12 +7,19 @@
 /** The one HTTPS port Bivy claims on the machine's tailnet name. */
 export const SERVE_HTTPS_PORT = 443;
 
-/** `{ running, hostname }` from `tailscale status --json` output. */
+/**
+ * `{ running, hostname, owner }` from `tailscale status --json` output. `owner`
+ * is the login of the user this machine belongs to, or null for a tagged
+ * machine (owned by tags, not a person).
+ */
 export function parseTailscaleStatus(text) {
   let status;
-  try { status = JSON.parse(text); } catch { return { running: false, hostname: null }; }
+  try { status = JSON.parse(text); } catch { return { running: false, hostname: null, owner: null }; }
   const hostname = String(status?.Self?.DNSName ?? "").replace(/\.$/, "") || null;
-  return { running: status?.BackendState === "Running", hostname };
+  const tagged = Array.isArray(status?.Self?.Tags) && status.Self.Tags.length > 0;
+  const login = status?.User?.[String(status?.Self?.UserID)]?.LoginName;
+  const owner = !tagged && typeof login === "string" && login.includes("@") ? login : null;
+  return { running: status?.BackendState === "Running", hostname, owner };
 }
 
 /** Where `tailscale serve` should send the machine's HTTPS traffic. */

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