@bivy/bivy 0.20.0 → 0.20.1-staging.10

package/README.md

@@ -11,6 +11,11 @@ Pi, OpenCode and other agents on your own machine. Reach them from a browser or
 your phone, with the live session, its terminal, its approvals, and the app
 they're building right in the chat. Try it, mark what's wrong, and send it back.
 
+<p align="center">
+  <img src="docs/images/preview-feedback-loop.gif" width="360"
+       alt="On a phone: open the app an agent built, circle the packed items, send a note, and compare the result before and after the agent's fix.">
+</p>
+
 Bivy is not another coding agent and not a cloud development machine. The agent
 stays local and does the coding with your model provider. Your repos, tools,
 databases, and services stay where they are. Bivy gives you remote access to all

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,8 +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";
 
@@ -76,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);
 }
@@ -2132,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(
@@ -2521,18 +2549,18 @@ async function cmdContext(args = []) {
   console.log(`\nEverything else: ${c.cyan("bivy help")} (or ${c.cyan("bivy help --json")}).`);
 }
 
-// `bivy suggest "<task>" [--title "…"] [--session <id>]` — propose a task the
-// user can start in one tap, beside this session or in it. For an agent
+// `bivy suggest "<task>" [--title "…"] [--run here|subagents|new] [--session <id>]`
+// — propose a task the user can start in one tap, in this session or beside it. For an agent
 // offering next steps: write the task as a complete instruction.
 async function cmdSuggest(args = []) {
-  const usage = 'Usage: bivy suggest "<task>" [--title "short label"] [--session <id>] [--json]';
+  const usage = 'Usage: bivy suggest "<task>" [--title "short label"] [--run here|subagents|new] [--session <id>] [--json]';
   if (args.includes("-h") || args.includes("--help")) {
-    console.log(`${usage}\n\nPost a task the user can start in one tap, in this session or in a parallel one that works in its own copy of the project. Write it as a complete instruction, with paths relative to the project root. --json prints {"ok","id"}.`);
+    console.log(`${usage}\n\nPost a task the user can start in one tap: in this session, through your sub-agents, or in a parallel session that works in its own copy of the project. Write it as a complete instruction, with paths relative to the project root.\n\n--run says where you recommend running it, which becomes the card's main button: 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 the user will want to follow in its own session). Without it, one card recommends here and several recommend new.\n\n--json prints {"ok","id"}.`);
     return;
   }
   const json = wantsJson(args);
   const fail = (error) => cliError(error, { json, paint: c.red });
-  const flagsWithValue = new Set(["--session", "--title"]);
+  const flagsWithValue = new Set(["--session", "--title", "--run"]);
   const flag = (name) => {
     const i = args.indexOf(name);
     return i >= 0 && i + 1 < args.length ? args[i + 1] : undefined;
@@ -2540,10 +2568,12 @@ async function cmdSuggest(args = []) {
   const text = args.filter((a, i) => !a.startsWith("-") && !(i > 0 && flagsWithValue.has(args[i - 1]))).join(" ").trim();
   const sessionId = resolveAttachSessionId({ sessionFlag: flag("--session"), env: process.env });
   if (!text) return fail({ code: "usage", message: usage, exit: EXIT.usage });
+  const run = flag("--run");
+  if (run !== undefined && !["here", "subagents", "new"].includes(run)) return fail({ code: "usage", message: `--run is here, subagents or new (got "${run}").`, 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, "suggest", { text, title: flag("--title") }).catch((error) => error);
+  const res = await sessionPost(config, sessionId, "suggest", { text, title: flag("--title"), run }).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("Suggest", res.status, body));
@@ -2551,6 +2581,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) {
@@ -4474,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;
@@ -4581,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();
@@ -4602,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",
@@ -4651,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
@@ -4690,6 +4750,19 @@ async function cmdSetup(args = []) {
     }
   }
 
+  // The terminal path to the same loop: the agent's own command starts a Bivy
+  // session, so work begun in a terminal shows up in the app and reaches the
+  // phone. Offered after sign-in, which runs the real agent.
+  const shimAgent = setupAgent?.command;
+  if (agentReady && shimAgent && AGENT_INTEGRATIONS.has(shimAgent) && !loadShims().shims[shimAgent]) {
+    console.log(`\nWhen you type '${shimAgent}' in a terminal, Bivy can run it as a session: it shows up in the app, and your phone hears when it finishes or needs you.`);
+    if (await askYesNo(`Start a Bivy session whenever you run '${shimAgent}'?`, true)) {
+      rl.pause();
+      await run(nodeBin, [selfScript, "shim", "install", shimAgent], { env: process.env });
+      rl.resume();
+    }
+  }
+
   // Materialize canonical typed config before starting/restarting the daemon,
   // so this setup run's workspace/port/agent choices are effective immediately.
   // Existing config keeps every advanced field.
@@ -4731,6 +4804,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'"}`);
@@ -4739,7 +4813,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);
@@ -4926,8 +5000,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.
@@ -5122,7 +5198,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})`) : "");
@@ -5287,6 +5363,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.
@@ -5671,6 +5754,193 @@ async function cmdLinkPhone(args = []) {
   }
 }
 
+const tailscaleConfigPath = path.join(appDir, "tailscale.json");
+const LOCAL_TOKEN_NAMES = ["Bivy CLI", "Local Remote UI"];
+
+function runTailscale(args) {
+  const res = spawnSync("tailscale", args, { encoding: "utf8" });
+  if (res.error?.code === "ENOENT") return null;
+  return { ok: res.status === 0, stdout: res.stdout ?? "", stderr: res.stderr ?? "" };
+}
+
+async function printPairLink(config) {
+  const data = await localApi(config, "/api/auth/pair-codes", { method: "POST", body: "{}" });
+  if (!data?.url) throw new Error("The node did not return a pairing link.");
+  const qr = terminalQr(data.url);
+  if (qr) console.log(qr);
+  console.log(`\nOpen on your phone (single use, 10 minutes):\n${c.cyan(data.url)}\n`);
+}
+
+// `bivy tailscale` — reach this machine from anywhere on your tailnet with no
+// control plane or relay: `tailscale serve` puts HTTPS on the machine's ts.net
+// name and forwards it to the node's direct listener, which serves the web app.
+async function cmdTailscale(args = []) {
+  const [verb = "on"] = args;
+  if (args.includes("-h") || args.includes("--help") || !["on", "pair", "status", "devices", "revoke", "off"].includes(verb)) {
+    console.log(`Usage: bivy tailscale [on|pair|status|devices|revoke <id>|off]
+
+  on           Serve this machine's Bivy on https://<machine>.<tailnet>.ts.net (tailnet only) and show a pairing link
+  pair         Show a new one-time pairing link for another device
+  status       Show the Tailscale address and whether it is served
+  devices      List the devices holding a token for this node
+  revoke <id>  Revoke a device's token and disconnect it
+  off          Stop serving Bivy over Tailscale`);
+    return;
+  }
+  const config = loadConfig();
+  if (!(await isReachable(config))) {
+    console.log(c.yellow(`The node is not reachable at ${url(config)}. Start it first: ${c.cyan(config.service ? "bivy restart" : "bivy start")}`));
+    process.exitCode = EXIT.unavailable;
+    return;
+  }
+  const saved = (() => { try { return JSON.parse(fs.readFileSync(tailscaleConfigPath, "utf8")); } catch { return null; } })();
+
+  if (verb === "pair") {
+    if (!saved) { console.log(`Tailscale access is off. Turn it on with ${c.cyan("bivy tailscale")}.`); process.exitCode = EXIT.failed; return; }
+    await printPairLink(config);
+    return;
+  }
+  if (verb === "devices") {
+    // The CLI and loopback web client mint their own tokens on this machine; list them as a count.
+    const all = (await localApi(config, "/api/auth/devices")) ?? [];
+    const devices = all.filter((device) => !LOCAL_TOKEN_NAMES.includes(device.name));
+    for (const device of devices) console.log(`${c.cyan(device.id)}  ${device.name}${device.createdAt ? c.dim(`  paired ${device.createdAt}`) : ""}`);
+    if (!devices.length) console.log("No paired devices.");
+    if (all.length > devices.length) console.log(c.dim(`(+${all.length - devices.length} tokens used on this machine by the CLI)`));
+    return;
+  }
+  if (verb === "revoke") {
+    const id = args[1];
+    if (!id) { console.log("Usage: bivy tailscale revoke <id>  (ids from 'bivy tailscale devices')"); process.exitCode = EXIT.usage; return; }
+    const res = await fetch(`${url(config)}/api/auth/devices/${encodeURIComponent(id)}`, { method: "DELETE", headers: { authorization: `Bearer ${await localDeviceToken(config)}` } });
+    if (!res.ok) { console.log(c.yellow(`No device ${id}.`)); process.exitCode = EXIT.notFound; return; }
+    console.log(`${c.green("✓")} Revoked ${id}.`);
+    return;
+  }
+  if (verb === "status") {
+    console.log(saved ? `${c.green("✓")} Served on ${c.cyan(`https://${saved.hostname}`)} (tailnet only) → 127.0.0.1:${saved.port}` : `Tailscale access is off. Turn it on with ${c.cyan("bivy tailscale")}.`);
+    return;
+  }
+  if (verb === "off") {
+    if (saved) {
+      const state = serveState(runTailscale(["serve", "status", "--json"])?.stdout, saved.hostname);
+      if (state.target === `http://127.0.0.1:${saved.port}`) runTailscale(serveOffArgs());
+    }
+    fs.rmSync(tailscaleConfigPath, { force: true });
+    await localApi(config, "/api/direct/reload", { method: "POST", body: "{}" });
+    console.log(`${c.green("✓")} Bivy is no longer served over Tailscale. Paired devices keep their tokens; see them with 'bivy tailscale devices' and revoke with 'bivy tailscale revoke <id>'.`);
+    return;
+  }
+
+  const status = runTailscale(["status", "--json"]);
+  if (!status) {
+    console.log(`${c.yellow("Tailscale isn't installed.")} Install it from ${c.cyan("https://tailscale.com/download")} (Arch: ${c.cyan("sudo pacman -S tailscale && sudo systemctl enable --now tailscaled")}), sign in with ${c.cyan("sudo tailscale up")}, then run ${c.cyan("bivy tailscale")} again.`);
+    process.exitCode = EXIT.unavailable;
+    return;
+  }
+  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;
+    return;
+  }
+  const port = saved?.port ?? await findAvailablePort(config.port + 2, "127.0.0.1");
+  const conflict = serveConflict(serveState(runTailscale(["serve", "status", "--json"])?.stdout, hostname), port);
+  if (conflict) {
+    console.log(c.yellow(conflict));
+    process.exitCode = EXIT.conflict;
+    return;
+  }
+  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) {
+    fs.rmSync(tailscaleConfigPath, { force: true });
+    await localApi(config, "/api/direct/reload", { method: "POST", body: "{}" }).catch(() => {});
+    console.error(c.red(`tailscale serve failed: ${(served?.stderr || served?.stdout || "").trim()}`));
+    const hint = serveFailureHint(served?.stderr);
+    if (hint) console.log(hint);
+    process.exitCode = EXIT.failed;
+    return;
+  }
+  console.log(c.bold(c.green(`\n  Bivy is on https://${hostname}\n`)));
+  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
@@ -6085,6 +6355,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;
@@ -6268,6 +6541,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

@@ -48,8 +48,10 @@ 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: "suggest", group: "session", scope: "session", json: true, usage: 'suggest "<task>" [--title "label"]', 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 or in a parallel one 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." } }, argv: ["suggest", { arg: "task" }, { flag: "--title", from: "title" }] }] },
+  { 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"],
     tools: [
       { name: "app_publish", description: "Give the user a live preview of something with a UI, from an app manifest file (web server port, static build, terminal, or desktop app). Run `bivy app --help` for the manifest format.", input: { manifest_path: { type: "string", description: "Path to the manifest JSON.", required: true } }, argv: ["app", "publish", { arg: "manifest_path" }] },
@@ -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" },
@@ -103,6 +106,8 @@ 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/guides/talk-to-the-user.md

@@ -28,9 +28,25 @@ Ask only when you can't reasonably decide yourself.
 
     bivy suggest "Add a GET /version endpoint that returns the package version." --title "Add /version"
 
-Each suggestion is a card the user can start in one tap, here or in a parallel
-session with its own copy of the project. Write it as a complete instruction with
-paths relative to the project root. Post one per idea instead of a bulleted list.
+Each suggestion is a card the user can start in one tap: here, through your
+sub-agents, or in a parallel session with its own copy of the project. Write it as
+a complete instruction with paths relative to the project root. Post one per idea
+instead of a bulleted list.
+
+`--run` picks the card's main button; the others stay one tap away:
+
+| `--run` | When |
+|---|---|
+| `here` | It builds on this conversation, or it's small. Default for a single card. |
+| `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?
 

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.