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

package/bin/bivy.mjs

@@ -40,6 +40,7 @@ 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 { 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 { hasConfiguredService as configuredServiceExists } from "./service-state.mjs";
@@ -2553,6 +2554,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) {
@@ -5673,6 +5698,122 @@ 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 } = 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 }, 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("  Only devices on your tailnet can reach it. Pair each one 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("");
+  await printPairLink(config);
+}
+
 function printUninstallHelp() {
   console.log(`
 ${c.bold("bivy uninstall")} — remove Bivy and all its data from this machine
@@ -6087,6 +6228,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;
@@ -6270,6 +6414,9 @@ Unlike 'bivy run', these commands operate on governed background Runs with check
     case "link":
       await cmdLinkPhone(args);
       break;
+    case "tailscale":
+      await cmdTailscale(args);
+      break;
     case "relay:setup":
       await cmdRelaySetup(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"],
@@ -103,6 +105,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: "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

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

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+// Pure helpers for `bivy tailscale`: read `tailscale status --json` and
+// `tailscale serve status --json`, and build the `tailscale serve` arguments.
+// No process spawning here, so each decision is testable on its own.
+
+/** 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. */
+export function parseTailscaleStatus(text) {
+  let status;
+  try { status = JSON.parse(text); } catch { return { running: false, hostname: null }; }
+  const hostname = String(status?.Self?.DNSName ?? "").replace(/\.$/, "") || null;
+  return { running: status?.BackendState === "Running", hostname };
+}
+
+/** Where `tailscale serve` should send the machine's HTTPS traffic. */
+export function serveTarget(port) {
+  return `http://127.0.0.1:${port}`;
+}
+
+export function serveOnArgs(port) {
+  return ["serve", "--bg", `--https=${SERVE_HTTPS_PORT}`, serveTarget(port)];
+}
+
+export function serveOffArgs() {
+  return ["serve", `--https=${SERVE_HTTPS_PORT}`, "off"];
+}
+
+/**
+ * What already sits on `<hostname>:443`, from `tailscale serve status --json`:
+ * `funnel` when it is public (Tailscale Funnel), and the proxy target of `/`
+ * when something is served there. Bivy refuses to share a Funnel'd name, and
+ * refuses to replace a target that isn't its own.
+ */
+export function serveState(text, hostname) {
+  let status;
+  try { status = JSON.parse(text || "{}"); } catch { status = {}; }
+  const key = `${hostname}:${SERVE_HTTPS_PORT}`;
+  const handlers = status?.Web?.[key]?.Handlers ?? {};
+  return {
+    funnel: status?.AllowFunnel?.[key] === true,
+    target: typeof handlers["/"]?.Proxy === "string" ? handlers["/"].Proxy : null,
+    otherPaths: Object.keys(handlers).filter((p) => p !== "/"),
+  };
+}
+
+/** Why `bivy tailscale` can't take `<hostname>:443`, or null when it can. */
+export function serveConflict(state, port) {
+  if (state.funnel) return "Tailscale Funnel is on for this machine's HTTPS name, which would put Bivy on the public internet. Turn it off first: tailscale funnel reset";
+  if (state.target && state.target !== serveTarget(port)) return `tailscale serve already sends https:// on this machine to ${state.target}. Remove it first: tailscale serve --https=${SERVE_HTTPS_PORT} off`;
+  if (state.otherPaths.length) return `tailscale serve already has paths on this machine's HTTPS name (${state.otherPaths.join(", ")}). Remove them first: tailscale serve --https=${SERVE_HTTPS_PORT} off`;
+  return null;
+}
+
+/** A one-line hint for a failed `tailscale serve`, from its stderr. */
+export function serveFailureHint(stderr) {
+  const text = String(stderr ?? "");
+  if (/access denied|permission denied|must be root|operator/i.test(text)) return "Let your user manage Tailscale once: sudo tailscale set --operator=$USER";
+  if (/https.*not enabled|enable https|certificates/i.test(text)) return "Turn on HTTPS certificates for your tailnet (admin console → DNS → HTTPS Certificates), then run this again.";
+  return null;
+}

package/dist/agent-instructions.js

@@ -45,6 +45,8 @@ export const BIVY_AGENT_NOTE = [
         "project root. `--run` is the one you recommend: here when it builds on this conversation, subagents for " +
         "independent tasks you can split and supervise (only if you have sub-agents), new for bigger work worth its " +
         "own session.",
+    '- If this session\'s title (taken from the first message) doesn\'t say what the work is, or the work changes ' +
+        'direction: `bivy title "<short title>"`.',
     "- When you finish long work, get blocked, or need the user to look at something: " +
         '`bivy notify "<message>"` (a chat card, plus a push to their phone when they are away). To ask and wait for ' +
         'an answer: `bivy ask "<question>" [--option A --option B]` prints their answer (or use your own ask-the-user tool).',

package/dist/auth.js

@@ -112,6 +112,18 @@ export function isLoopbackAddress(address) {
     const addr = address.replace(/^::ffff:/, "");
     return addr === "127.0.0.1" || addr === "::1" || addr === "localhost";
 }
+// Sockets accepted by a listener that fronts remote callers through a local
+// proxy (`tailscale serve` forwards tailnet traffic from 127.0.0.1). Their peer
+// address is loopback, but the caller is not, so they never get loopback trust.
+const remoteSockets = new WeakSet();
+/** Treat every connection `server` accepts as remote, whatever its peer address. */
+export function markRemoteListener(server) {
+    server.on("connection", (socket) => remoteSockets.add(socket));
+}
+/** True when a request physically arrived over loopback from a local caller. */
+export function isLoopbackRequest(req) {
+    return !!req.socket && !remoteSockets.has(req.socket) && isLoopbackAddress(req.socket.remoteAddress);
+}
 export function extractToken(headerValue) {
     if (!headerValue)
         return null;
@@ -141,7 +153,7 @@ export function tokenFromRequest(req) {
  * `/api/auth/bootstrap`) can rely on it even when the general bypass in
  * `isAuthorized` is off. */
 export function resolveAuth(identity, req) {
-    const loopback = isLoopbackAddress(req.socket?.remoteAddress);
+    const loopback = isLoopbackRequest(req);
     const deviceId = identity.verifyToken(tokenFromRequest(req));
     return { deviceId, loopback };
 }
@@ -160,7 +172,8 @@ export function isAuthorized(ctx) {
  * web client (?local=1), a LAN device browsing the node directly, or CLI/native
  * clients (no Origin).
  * Remote phones reach the node through the relay, which the node dials
- * *outbound* — those never arrive here as inbound upgrades. So we allow only
+ * *outbound* — those never arrive here as inbound upgrades — or over Tailscale
+ * on the `*.ts.net` name, which counts as local here. So we allow only
  * local/private hostnames and reject a public Host (rebinding) or public Origin
  * (cross-site). Escape hatches: BIVY_ALLOWED_HOSTS (comma-separated extra
  * hostnames, e.g. a reverse-proxy domain) and BIVY_ALLOW_ANY_ORIGIN=1.
@@ -272,7 +285,7 @@ export function authMiddleware(identity, sessionTokens) {
                 return;
             }
             sessionTokens.used?.(sessionId, call);
-            req.auth = { deviceId: null, loopback: isLoopbackAddress(req.socket?.remoteAddress), sessionId };
+            req.auth = { deviceId: null, loopback: isLoopbackRequest(req), sessionId };
             next();
             return;
         }

package/dist/pair-codes.js

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+//
+// One-time pairing codes for devices that reach the node directly (over
+// Tailscale). The owner mints a code on the machine (`bivy tailscale pair`),
+// the phone opens `https://<machine>.ts.net/#pair=<code>` and trades the code
+// for a device token. Codes are single-use, short-lived and held only in
+// memory, so a restart invalidates every outstanding one.
+import { createHash, randomBytes } from "node:crypto";
+export const PAIR_CODE_TTL_MS = 10 * 60 * 1000;
+const digest = (code) => createHash("sha256").update(code).digest("hex");
+export class PairCodes {
+    now;
+    // Keyed by the code's hash, so a lookup never compares secrets directly.
+    pending = new Map();
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    issue(ttlMs = PAIR_CODE_TTL_MS) {
+        this.sweep();
+        const code = randomBytes(24).toString("base64url");
+        const expiresAt = this.now() + ttlMs;
+        this.pending.set(digest(code), expiresAt);
+        return { code, expiresAt };
+    }
+    /** True once per valid, unexpired code; the code is spent either way. */
+    redeem(code) {
+        if (!code)
+            return false;
+        const key = digest(code);
+        const expiresAt = this.pending.get(key);
+        this.pending.delete(key);
+        return expiresAt !== undefined && expiresAt > this.now();
+    }
+    sweep() {
+        const now = this.now();
+        for (const [key, expiresAt] of this.pending)
+            if (expiresAt <= now)
+                this.pending.delete(key);
+    }
+}

package/dist/remote/direct.js

@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+//
+// Direct access over Tailscale: no control plane, no relay. `bivy tailscale`
+// writes `<data-dir>/tailscale.json` and points `tailscale serve` (HTTPS on the
+// machine's ts.net name, tailnet only) at a loopback port; the node opens that
+// port as its direct listener. Every connection on it is treated as remote, so
+// callers need a device token, which a phone gets by redeeming a pairing code.
+import fs from "node:fs";
+import path from "node:path";
+export const DIRECT_CONFIG_FILE = "tailscale.json";
+export function loadDirectListenerConfig(appDir) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(appDir, DIRECT_CONFIG_FILE), "utf8"));
+        const port = Number(raw.port);
+        if (!Number.isInteger(port) || port <= 0 || port > 65535)
+            return null;
+        return { port, hostname: typeof raw.hostname === "string" && raw.hostname ? raw.hostname : undefined };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/remote/index.js

@@ -12,3 +12,4 @@
 // promote to a standalone `@bivy/remote` npm package.
 export { RelayConnector, loadRelayConfig } from "./relay-client.js";
 export { soloCredentials, buildDialUrl } from "./solo.js";
+export { loadDirectListenerConfig, DIRECT_CONFIG_FILE } from "./direct.js";

package/dist/server.js

@@ -84,8 +84,11 @@ import { canOpenBrowser, openBrowser } from "./browser-open.js";
 import { openOAuthLoginOnNode } from "./runtime/oauth/oauth-node-open.js";
 import { collectNodeStats } from "./node-stats.js";
 import { SessionEventCoalescer } from "./session-event-coalescer.js";
-import { authMiddleware, resolveAuth, isAuthorized, requestOriginAllowed } from "./auth.js";
-import { RelayConnector, loadRelayConfig, soloCredentials } from "./remote/index.js";
+import { authMiddleware, resolveAuth, isAuthorized, requestOriginAllowed, markRemoteListener } from "./auth.js";
+import { PairCodes } from "./pair-codes.js";
+import http from "node:http";
+import { webAppDirs, webAppRouter } from "./web-app.js";
+import { RelayConnector, loadRelayConfig, loadDirectListenerConfig, soloCredentials } from "./remote/index.js";
 import { readEphemeralTeardownConfig, shouldSelfTeardown, snapshotsDurableForTeardown, performSelfTeardown } from "./ephemeral-teardown.js";
 import { buildSessionSnapshot, applySessionSnapshot } from "./session/snapshot.js";
 import { clearTurnActivity } from "./session/turn-activity.js";
@@ -1070,9 +1073,16 @@ const accessDevices = createAccessDeviceController({
     create: (name) => identity.createDevice(name),
     revoke: (id) => identity.revokeDevice(id),
     onCreated: (device) => broadcast({ type: "device.created", device }),
-    onRevoked: (id) => broadcast({ type: "device.revoked", id }),
+    onRevoked: (id) => {
+        broadcast({ type: "device.revoked", id });
+        // A revoked token loses its open sockets now, not at its next reconnect.
+        for (const socket of clients)
+            if (socketDeviceIds.get(socket) === id)
+                socket.close(1008, "Unauthorized");
+    },
 });
 const clients = new Set();
+const socketDeviceIds = new WeakMap();
 const commandProcesses = new Map();
 const oauthLogins = new Map();
 // A browser-initiated subscription login parks the node on `manualCodePromise`
@@ -2518,10 +2528,7 @@ const RELAY_COMMANDS = {
         const rec = resolveSession(sid);
         if (!rec)
             return;
-        rec.session.setName(newName);
-        persistSessionMetadata(rec);
-        ctx.broadcast({ type: "session.renamed", sessionId: rec.id, sessionFile: rec.sessionFile, name: newName });
-        scheduleAdvertise();
+        sessionNamer.setSessionName(rec, newName);
     },
     abort(msg, ctx) {
         const sessionId = String(msg.sessionId ?? "");
@@ -9337,7 +9344,8 @@ app.use((_req, res, next) => {
 // (OAuth callback, GitHub App manifest). It does NOT host the web UI — the
 // React/Vite PWA (@bivy/web) is served exclusively by the hosted or self-hosted
 // control plane. `/` returns a small informational stub for anyone who points a
-// browser straight at the node.
+// browser straight at the node. The one exception is the direct listener for
+// `bivy tailscale` (below), which has no control plane and serves the app itself.
 app.get("/", (_req, res) => {
     res.setHeader("Cache-Control", "no-store, max-age=0");
     res
@@ -9447,6 +9455,20 @@ app.post("/api/auth/bootstrap", sensitiveRateLimiter, (req, res) => {
     const { device, token } = accessDevices.create(name);
     res.json({ ok: true, device, token });
 });
+// Pairing a device that reaches the node directly (Tailscale): trade a one-time
+// code minted on this machine for a device token. Registered before the auth
+// middleware because the caller has no token yet; the code is the credential.
+const pairCodes = new PairCodes();
+app.post("/api/auth/pair", sensitiveRateLimiter, (req, res) => {
+    if (!requestOriginAllowed(req))
+        return res.status(403).json({ error: "Forbidden origin" });
+    if (!pairCodes.redeem(String(req.body?.code ?? ""))) {
+        return res.status(401).json({ error: "This pairing link is used or expired. Run 'bivy tailscale pair' on your machine for a new one." });
+    }
+    const name = String(req.body?.name ?? "").trim().slice(0, 80) || "Paired device";
+    const { device, token } = accessDevices.create(name);
+    res.json({ ok: true, device, token });
+});
 // All other /api routes require auth (loopback may bypass, per config and host
 // — see loopbackAllowed()/isMultiUserHost() in src/auth.ts).
 app.use("/api", authMiddleware(identity, {
@@ -9457,6 +9479,23 @@ app.use("/api", authMiddleware(identity, {
     used: (sessionId, call) => { if (call.method !== "GET")
         auditLog.record({ kind: "agent.call", session: sessionId, tool: `${call.method} ${call.path}` }); },
 }));
+// Mint a pairing code for a direct (Tailscale) device. Only callers already
+// trusted by this node get one: the owner's CLI, or an already-paired device.
+app.post("/api/auth/pair-codes", (_req, res) => {
+    const direct = loadDirectListenerConfig(appDir);
+    const { code, expiresAt } = pairCodes.issue();
+    const url = direct?.hostname ? `https://${direct.hostname}/#pair=${code}` : undefined;
+    res.json({ ok: true, code, expiresAt, url });
+});
+// Start, move or stop the direct listener after `bivy tailscale` changes it.
+app.post("/api/direct/reload", async (_req, res, next) => {
+    try {
+        res.json({ ok: true, ...(await reloadDirectListener()) });
+    }
+    catch (error) {
+        next(error);
+    }
+});
 // Reload relay.json without forcing the user to restart the whole node. This is
 // used by `bivy relay:setup` after it enrolls the node.
 app.post("/api/relay/reload", (_req, res) => {
@@ -9823,10 +9862,7 @@ app.post("/api/sessions/rename", (req, res, next) => {
         const rec = resolveSession(sid);
         if (!rec)
             return res.status(404).json({ error: "Session not found" });
-        rec.session.setName(newName);
-        persistSessionMetadata(rec);
-        broadcast({ type: "session.renamed", sessionId: rec.id, sessionFile: rec.sessionFile, name: newName });
-        scheduleAdvertise();
+        sessionNamer.setSessionName(rec, newName);
         res.json({ ok: true, name: newName });
     }
     catch (error) {
@@ -11665,6 +11701,19 @@ app.get("/api/session/:id/automations/apply/:proposalId", (req, res) => {
         return res.status(404).json({ error: "Proposal not found" });
     res.json(proposal);
 });
+// `bivy title "<title>"`: the agent names its own session, e.g. when the first
+// message made a poor title or the work changed direction.
+const MAX_SESSION_TITLE = 100;
+app.post("/api/session/:id/title", (req, res) => {
+    const record = openSessions.get(String(req.params.id));
+    if (!record)
+        return res.status(404).json({ error: "Session not found" });
+    const title = typeof req.body?.title === "string" ? req.body.title.replace(/\s+/g, " ").trim() : "";
+    if (!title || title.length > MAX_SESSION_TITLE)
+        return res.status(400).json({ error: `A title needs 1 to ${MAX_SESSION_TITLE} characters.` });
+    sessionNamer.setSessionName(record, title);
+    res.json({ ok: true, title });
+});
 // `bivy suggest "<task>"`: the agent proposes a task the user can start in one
 // tap, here, through this agent's sub-agents, or in a parallel session; `run`
 // is the one the agent recommends (see packages/web SuggestionCard).
@@ -12007,6 +12056,7 @@ const server = app.listen(port, host, async () => {
     console.log(`Agent data dir: ${piDir}`);
     console.log(`Workspace: ${defaultWorkspace}`);
     startRelayIfConfigured();
+    void reloadDirectListener().catch((error) => console.error("[direct] Could not start the direct listener:", error instanceof Error ? error.message : error));
     void syncAgentBridges().catch((error) => console.warn("[bridges] Could not install agent bridges; they will install on first use:", error instanceof Error ? error.message : error));
     if (appGateway) {
         appGateway.server.on("error", (error) => { console.error("[apps] Preview gateway could not start:", error); shutdown("preview gateway failure"); });
@@ -12073,6 +12123,46 @@ server.on("error", (error) => {
     process.exit(1);
 });
 const wss = new WebSocketServer({ server, path: "/ws" });
+// Direct listener (`bivy tailscale`): the same API and WebSocket, plus the web
+// app, on a loopback port `tailscale serve` exposes to the tailnet over HTTPS.
+// markRemoteListener keeps its proxied, loopback-looking connections from ever
+// getting loopback trust; every caller needs a device token.
+const directWebApp = webAppRouter(webAppDirs(repoRoot));
+let directListener = null;
+async function reloadDirectListener() {
+    const config = loadDirectListenerConfig(appDir);
+    if (directListener && directListener.port !== config?.port) {
+        const previous = directListener;
+        directListener = null;
+        for (const client of previous.wss.clients)
+            client.terminate();
+        previous.wss.close();
+        previous.server.closeAllConnections();
+        await new Promise((resolve) => previous.server.close(() => resolve()));
+    }
+    if (config && !directListener) {
+        const directApp = express();
+        directApp.disable("x-powered-by");
+        if (directWebApp)
+            directApp.use(directWebApp);
+        directApp.use(app);
+        const listener = http.createServer(directApp);
+        markRemoteListener(listener);
+        const directWss = new WebSocketServer({ server: listener, path: "/ws" });
+        directWss.on("connection", (socket, req) => wss.emit("connection", socket, req));
+        await new Promise((resolve, reject) => {
+            listener.once("error", reject);
+            listener.listen(config.port, "127.0.0.1", () => {
+                listener.off("error", reject);
+                resolve();
+            });
+        });
+        listener.on("error", (error) => console.error("[direct] Listener error:", error));
+        directListener = { port: config.port, server: listener, wss: directWss };
+        console.log(`[direct] Listening on 127.0.0.1:${config.port}${config.hostname ? ` for https://${config.hostname}` : ""}${directWebApp ? "" : " (web app not built; API only)"}`);
+    }
+    return { enabled: Boolean(directListener), port: directListener?.port, webApp: Boolean(directWebApp) };
+}
 wss.on("connection", (socket, req) => {
     // Reject cross-origin / DNS-rebinding upgrades before auth: loopback bypasses
     // auth by default, so a page the user merely visited could otherwise open a
@@ -12081,11 +12171,14 @@ wss.on("connection", (socket, req) => {
         socket.close(1008, "Forbidden origin");
         return;
     }
-    if (!isAuthorized(resolveAuth(identity, req))) {
+    const socketAuth = resolveAuth(identity, req);
+    if (!isAuthorized(socketAuth)) {
         socket.close(1008, "Unauthorized");
         return;
     }
     clients.add(socket);
+    if (socketAuth.deviceId)
+        socketDeviceIds.set(socket, socketAuth.deviceId);
     // Terminals opened on this socket; closed when the socket disconnects so a
     // dropped browser tab doesn't leak shells. Output is unicast to this socket.
     const ownedTerminals = new Set();

package/dist/session/session-namer.js

@@ -180,6 +180,12 @@ export function createSessionNamer(deps) {
                 catch (error) {
                     console.warn("Session naming suggestion failed", error);
                 }
+                // A title set while the model was thinking (the user, or the agent with
+                // `bivy title`) wins over the refinement.
+                if (record.session.getName() !== fallback) {
+                    record.namedFromFirstPrompt = true;
+                    return;
+                }
                 if (finalName !== fallback) {
                     record.session.setName(finalName);
                     deps.persistSessionMetadata(record);
@@ -211,8 +217,8 @@ export function createSessionNamer(deps) {
             record.naming = false;
         }
     }
-    /** Manually set a session's title (e.g. GitHub-issue pickup) and lock it so the
-     *  first-prompt namer won't overwrite it. */
+    /** Manually set a session's title (a rename in the app, `bivy title`, a
+     *  GitHub-issue pickup) and lock it so the first-prompt namer won't overwrite it. */
     function setSessionName(record, name) {
         const clean = name.trim();
         if (!clean)

package/dist/session/session-tokens.js

@@ -44,7 +44,7 @@ export function createSessionTokenCodec(key = randomBytes(32)) {
  */
 export const SESSION_TOKEN_ROUTES = [
     { method: "GET", path: /^\/api\/session\/([^/]+)\/context$/, session: "path" },
-    { method: "POST", path: /^\/api\/session\/([^/]+)\/(attach|suggest|notify)$/, session: "path" },
+    { method: "POST", path: /^\/api\/session\/([^/]+)\/(attach|suggest|notify|title)$/, session: "path" },
     { method: "POST", path: /^\/api\/session\/([^/]+)\/ask$/, session: "path" },
     { method: "GET", path: /^\/api\/session\/([^/]+)\/ask\/[^/]+$/, session: "path" },
     { method: "POST", path: /^\/api\/session\/([^/]+)\/ask\/[^/]+\/wait$/, session: "path" },